Adding a Logo to a QR Code in Python: Error Correction and Pillow
Add a logo to a Python-generated QR code while keeping it scannable. Learn which error correction level to choose and how to paste a transparent logo with Pillow.

Generating a QR code in Python is straightforward, but adding a centered logo without destroying scannability requires the right error correction level and image handling. With the qrcode library and Pillow, you can render the QR matrix as an image and paste a logo in the center. The key points are to choose at least level Q (preferably H), keep the logo at about 20–25% of the QR code's width, and use the logo's alpha channel as a mask when pasting.
QR Code Error Correction Levels
QR codes use Reed-Solomon error correction to recover data when parts of the code are damaged or obscured. The specification defines four levels:
| Level | Recovery Capacity | Typical Use |
|---|---|---|
| L | ~7% | High-density codes, minimal damage |
| M | ~15% | General purpose |
| Q | ~25% | Industrial, partial obstruction |
| H | ~30% | Logo placement, heavy damage |
The correction capacity is a property of the encoded codewords, not a simple pixel-area percentage. Still, the higher the level, the more obscured modules a scanner can tolerate. For a logo whose width is about 15–25% of the QR code width, level H is a common starting point. Level Q may work with a small logo and a short payload, but H gives more margin for real-world test results.
Required Libraries
The most widely used Python library for generating QR codes is qrcode. Install it with the pil extra so it can render Pillow images:
pip install qrcode[pil]This installs both qrcode and Pillow. The library builds the QR matrix and make_image() returns a PIL image you can edit.
Generate a Basic QR Code
Start with a QRCode object, set the error correction level, add data, and render the image.
import qrcode
from qrcode.constants import ERROR_CORRECT_H
qr = qrcode.QRCode(
version=None, # auto-determine size
error_correction=ERROR_CORRECT_H,
box_size=10,
border=4,
)
qr.add_data('https://example.com')
qr.make(fit=True)
img = qr.make_image(fill_color='black', back_color='white')
img.save('qr_without_logo.png')version=None lets the library choose the smallest QR version that fits the data and error correction level. box_size sets the pixel size of each module, and border sets the quiet zone in modules.
Add a Logo With Pillow
Open the QR image and the logo, resize the logo, and paste it in the center. Use the logo's alpha channel as the paste mask so transparent pixels do not overwrite QR modules.
from PIL import Image
# Open the QR code image as RGBA so it can be composited with a mask
qr_img = Image.open('qr_without_logo.png').convert('RGBA')
# Open and resize the logo, preserving transparency
logo = Image.open('logo.png').convert('RGBA')
logo_size = int(qr_img.size[0] * 0.2) # 20% of the QR image width
logo = logo.resize((logo_size, logo_size), Image.LANCZOS)
# Center the logo
pos = ((qr_img.size[0] - logo_size) // 2, (qr_img.size[1] - logo_size) // 2)
# Paste only the opaque parts of the logo
qr_img.paste(logo, pos, logo)
qr_img.convert('RGB').save('qr_with_logo.png')Passing logo as the third argument to paste() uses its alpha channel as the mask. For a rectangular logo without transparency, the full rectangle will replace the underlying modules, so test whether the remaining error correction level is sufficient.
Balance Logo Size and Error Correction Capacity
Logo size is usually described as a fraction of the QR code width. A square logo sized to 20% of the width covers about 4% of the total pixel area, but that statistic alone is not enough. What matters is which data modules the logo obscures and how the error correction blocks are distributed. A centered logo can cross several blocks, so test with the exact logo.
As a practical rule, keep the logo width between 15% and 25% of the QR code width. At 25%, level H is a safer choice than Q. If you need higher data capacity, reduce the logo size or use a smaller payload. If your logo has transparent areas, those areas do not destroy modules, which can let you use a larger visual logo.
Scanning Reliability and Edge Cases
Even with level H, an oversized or badly placed logo can make the QR code unreadable.
- Logo shape: Use a PNG with transparency if possible. A circular or irregular logo with transparent edges covers less data than a rectangular one.
- Quiet zone: Keep the logo away from the three finder patterns. A centered logo is safe, but avoid letting it extend into the timing patterns.
- Scanner testing: Test with multiple devices and apps. What scans on one app may fail on another.
- Color contrast: Keep the dark modules dark and the background light. Do not let the logo blend into the QR modules.
- Logo padding: A thin white border around the logo can improve separation, but it also covers more area. Keep it thin.
If you generate many QR codes with the same logo, resize the logo once and reuse it instead of resizing it for every output.
Performance and Production Considerations
Generating a single QR code with a logo is inexpensive, but a service that generates many images can still benefit from a few optimizations.
- Caching: Cache generated images by data and error correction level when the same payload is requested repeatedly.
- Image format: Use PNG. Lossy formats such as JPEG introduce artifacts that can interfere with scanning.
- Concurrency: QR generation is CPU-bound. If you generate many images at once, a process pool is usually more useful than a thread pool.
- Logo pre-processing: Resize and hold the logo in memory so it does not have to be reloaded for every code.
- In-memory output: Use
BytesIOwhen serving images over HTTP instead of writing temporary files to disk.
Build a Reusable Function
Encapsulate the workflow in a function that takes the data, logo path, error correction level, and sizing options as parameters.
from io import BytesIO
import qrcode
from qrcode.constants import ERROR_CORRECT_H
from PIL import Image
def make_qr_with_logo(
data,
logo_path,
output_path=None,
box_size=10,
border=4,
logo_ratio=0.2,
error_correction=ERROR_CORRECT_H,
):
qr = qrcode.QRCode(
version=None,
error_correction=error_correction,
box_size=box_size,
border=border,
)
qr.add_data(data)
qr.make(fit=True)
qr_img = qr.make_image(fill_color='black', back_color='white').convert('RGBA')
logo = Image.open(logo_path).convert('RGBA')
logo_size = int(qr_img.size[0] * logo_ratio)
logo = logo.resize((logo_size, logo_size), Image.LANCZOS)
pos = ((qr_img.size[0] - logo_size) // 2, (qr_img.size[1] - logo_size) // 2)
qr_img.paste(logo, pos, logo)
if output_path:
qr_img.convert('RGB').save(output_path)
else:
buf = BytesIO()
qr_img.convert('RGB').save(buf, format='PNG')
return buf.getvalue()The function defaults to ERROR_CORRECT_H, a safe choice for a 20% logo width. logo_ratio is the logo width as a fraction of the QR image width. If testing shows level Q works for your data and logo, import ERROR_CORRECT_Q from qrcode.constants and pass it as error_correction. Always verify the final image with a real scanner, because actual recovery depends on the logo shape, the QR version, and the scanner.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.