Last month I printed 250 tickets for a company offsite. Each ticket carried a QR code pointing at our check-in form. On the morning of the event, roughly a third of them refused to scan. The phone camera would focus, hesitate, and give up. No error message, nothing.
The codes looked perfect on my screen, so I blamed the print shop. Wrong call. The problem was in how I generated them, and it took me an evening of regenerating all 250 codes to understand exactly how many ways a printed QR code can fail. Here is the whole process, so you can skip the 11pm panic.
Method 1: Python with the qrcode library
This is what I should have done the first time. Python 3.11.8 with qrcode 8.0 and Pillow 11.1.0:
# gen_tickets.py
import csv
import qrcode
from qrcode.constants import ERROR_CORRECT_M
with open("tickets.csv", newline="") as f:
for row in csv.DictReader(f):
url = f"https://checkin.example.com/t?ticket={row['id']}"
qr = qrcode.QRCode(
error_correction=ERROR_CORRECT_M,
box_size=10,
border=4,
)
qr.add_data(url)
qr.make(fit=True)
img = qr.make_image(fill_color="black", back_color="white")
img.save(f"ticket-{row['id']}.png")
Two parameters carry most of the weight here. border=4 gives the code a quiet zone: four modules of blank white on every side. Scanners need that margin to find where the symbol starts, and I'll come back to what happens without it. ERROR_CORRECT_M means roughly 15% of the codewords can be damaged and the code still reads, which matters once a ticket goes through a lamination machine. The qrcode package on PyPI documents all four ECC levels; Denso Wave, the company that invented the format, publishes the original error correction spec if you want to know why the levels trade capacity for resilience.
The whole batch of 250 rendered in about four seconds on my laptop.
Method 2: qrencode from the command line
When I need codes without opening an editor, Ubuntu's qrencode package does the same job in one line. Version 4.1.1 on Ubuntu 24.04:
sudo apt install qrencode
qrencode -o ticket-T-0042.png -s 10 -m 4 -l M "https://checkin.example.com/t?ticket=T-0042"
-s 10 sets each module to 10 pixels, -m 4 adds the same four-module margin, -l M picks medium error correction. A shell loop over ticket IDs handles batches. I like this route for CI pipelines: no virtualenv, no pip, one apt line in the Dockerfile and the build never touches Python dependencies.
Method 3: an online generator for one-off codes
For a single code, none of that is worth the setup. I paste the URL into a free online QR code generator and download the PNG directly. Our marketing team keeps this browser-based QR tool bookmarked for poster work; it runs entirely client-side, so the URL never leaves the machine, and there is no account or watermark to fight with. When someone hands me a shortened link and I want to confirm it opens the right page, generating the code and scanning it with my phone takes fifteen seconds.
The three ways printed codes actually fail
1. The quiet zone got cropped. My first batch used border=0 to save ink, and the print layout cropped tight to the symbol. Phones could not lock onto the code at all. I verified with zbarimg from the zbar package: on a good code it prints QR-Code:https://checkin.example.com/t?ticket=T-0042; on the cropped one it printed no symbol and exited with status 4. Four modules of white margin, minimum. Print shops will trim it for you silently if you don't leave it in the file.
2. The URL grew past the symbol's capacity. When the marketing team asked for tracking, I appended ?utm_source=print&utm_medium=ticket&utm_campaign=offsite to every URL and, "for safety", bumped error correction to level H. qrcode 8.0 rejected the very first ticket:
qrcode.exceptions.DataOverflowError: Code length overflow
Capacity and error correction pull in opposite directions: level H dedicates 30% of the symbol to redundancy, so the same URL needs a denser, bigger grid, and past the limit the library just refuses. My fix was unglamorous. Shorter campaign parameters, back to level M. Denser codes are also harder for phone cameras to resolve on textured paper, which is a second reason not to max out the grid.
3. The colors were inverted. The poster version came back as white modules on navy blue. It scanned on zero devices I tried, including an iPhone 13 and a Pixel 7. Most decoders, from zbar to the iOS camera to Google Lens, expect dark modules on a light background, and inverted symbols are simply not recognized. zbarimg again reported nothing found. Keep dark-on-light. If brand colors force a dark background, put a white rounded card behind a normal dark code instead of recoloring the modules.
Quick reference
| Failure | Symptom | Fix |
|---|---|---|
| Quiet zone cropped | Camera focuses but never locks |
border=4 / -m 4; verify with zbarimg |
| Data too long | DataOverflowError: Code length overflow |
Shorter URL, lower ECC level |
| Inverted colors | Zero devices recognize the code | Dark modules on light background |
The second print run scanned on the first try, and I printed one proof ticket before sending the rest. That last habit is the real fix. Margin intact, payload small, colors dark-on-light, one physical test.
More free browser-based utilities at utilvy.com.
Top comments (0)