Learn How to Build a QR Code Generator in Python: Absolute Beginners Tutorial

QR codes are everywhere — on product packaging, restaurant menus, boarding passes, and business cards. Python lets you generate them in under ten lines of code. This tutorial walks through building a QR code generator from scratch, with no prior experience assumed.

A QR code (Quick Response code) is a two-dimensional matrix barcode that encodes data as a pattern of black and white squares. Smartphone cameras and dedicated scanner apps can read that pattern and decode it back into a URL, plain text, contact information, or any other string. Unlike a traditional barcode, a QR code holds significantly more data and can be read from any direction. When you generate one in Python, you are producing that exact square grid as an image file that can be printed, embedded in a web page, or distributed digitally.

What Is a QR Code and How Does It Store Data?

At a technical level, a QR code divides its area into small square modules. Each module is either dark or light, and the combination of all modules encodes a sequence of characters. The specification defines several data modes — numeric, alphanumeric, byte, and kanji — and Python's qrcode library handles mode selection automatically. The version of a QR code (an integer from 1 to 40) controls the grid size: version 1 produces a 21×21 module grid, and each additional version adds four modules per side, up to 177×177 at version 40.

One of the more interesting properties of a QR code is its built-in error correction. A portion of the encoded data is redundant, which allows a scanner to reconstruct the original content even if part of the code is damaged, dirty, or obscured. This redundancy is why you can place a logo on top of a QR code and it still scans correctly, as long as the obscured area does not exceed the recovery capacity of the chosen error correction level.

The four error correction levels in the QR code standard correspond to the constants qrcode.constants.ERROR_CORRECT_L, ERROR_CORRECT_M, ERROR_CORRECT_Q, and ERROR_CORRECT_H. The letters stand for Low, Medium, Quartile, and High, with recovery capacities of roughly 7%, 15%, 25%, and 30% respectively. Choosing a higher level produces a denser, more complex image because more of the grid is devoted to redundancy data.

Installing qrcode and Pillow

Both packages are installable from PyPI through pip. The qrcode[pil] notation installs the core library plus its Pillow dependency in a single command, which is the recommended approach. If your environment already has Pillow installed, you can install qrcode alone, but using the combined form avoids potential version mismatch issues.

pip install qrcode[pil]

After installation, verify it worked by opening a Python interpreter and importing the library:

import qrcode
print(qrcode.version_info)
# Expected output: something like (8, 0, 0)

Understanding QRCode Parameters

The qrcode.QRCode class accepts four main parameters that shape the output. Understanding each one before writing code prevents common issues such as a QR code that is too small to scan reliably or one that stores more data than intended.

Here is the minimal working example that corresponds to steps 1 through 3:

import qrcode

qr = qrcode.QRCode(
    version=1,
    error_correction=qrcode.constants.ERROR_CORRECT_M,
    box_size=10,
    border=4
)

qr.add_data("https://pythoncodecrack.com")
qr.make(fit=True)

img = qr.make_image(fill_color="black", back_color="white")
img.save("pythoncodecrack_qr.png")

Running this script saves a file named pythoncodecrack_qr.png in the same directory as the script. The image will be a standard black-on-white QR code. You can open it in any image viewer and scan it with a phone camera to confirm it decodes to the correct URL.

The reusable function version

Wrapping the generator in a function allows you to call it multiple times with different data and filenames without repeating the configuration block each time.

import qrcode


def generate_qr(
    data: str,
    filename: str,
    fill: str = "black",
    back: str = "white",
    error_level=qrcode.constants.ERROR_CORRECT_M
) -> None:
    """Generate a QR code image and save it to disk.

    Args:
        data:        The text or URL to encode.
        filename:    Output file path, e.g. 'output/my_qr.png'.
        fill:        Module (foreground) color. Default: 'black'.
        back:        Background color. Default: 'white'.
        error_level: Error correction constant. Default: ERROR_CORRECT_M.
    """
    qr = qrcode.QRCode(
        version=None,
        error_correction=error_level,
        box_size=10,
        border=4
    )
    qr.add_data(data)
    qr.make(fit=True)

    img = qr.make_image(fill_color=fill, back_color=back)
    img.save(filename)
    print(f"QR code saved to: {filename}")


# Example calls
generate_qr("https://pythoncodecrack.com", "pcc_qr.png")
generate_qr("https://pythoncodecrack.com", "pcc_qr_navy.png", fill="navy", back="lightyellow")
generate_qr(
    "Contact: Kandi Brian — pythoncodecrack.com",
    "contact_qr.png",
    error_level=qrcode.constants.ERROR_CORRECT_H
)

Notice that version=None is used in the function version. Combining version=None with fit=True is the cleanest approach because it lets the library choose the smallest version that accommodates the data, rather than starting at version 1 and potentially needing to expand. This removes the DataOverflowError risk entirely.

"Explicit is better than implicit." — The Zen of Python (PEP 20)

Python Learning Summary Points

1. The qrcode library abstracts the entire QR code encoding process. You pass it a string and it handles mode selection, error correction encoding, and matrix construction internally.
2. Setting version=None combined with fit=True is the safest configuration — it prevents DataOverflowError and ensures the smallest valid output regardless of data length.
3. Pillow color names follow CSS conventions and include hundreds of named colors. Any name that Pillow recognizes can be passed to fill_color and back_color, giving you precise control over the visual output without needing to work with hex values.
4. Wrapping your generator in a function with default parameter values is standard Python practice. It keeps your code DRY (Do Not Repeat Yourself) and makes it easy to generate multiple QR codes with different configurations from a single call site.

From here you can extend the generator in several directions: batch-generating QR codes from a CSV of URLs, embedding a logo image on top of the QR code using Pillow's compositing tools, or building a small web interface around the generator using Flask or FastAPI. Each of those projects builds directly on the same four-method pipeline you used here.