PySide6 QR Code Maker

A PySide6 desktop application for generating QR codes with live preview, batch export, and custom styling.

Aim of the project

This project was built to offer a dependable alternative to typical online QR generators. It supports batch QR creation, flexible styling options, and works fully offline with no watermarks, size limits, or tracking.

Features

Core capabilities

• Full QR specification support: all 40 QR versions and all error correction levels

Two generation modes

Text Mode: create QR codes for plain text, URLs, Wi-Fi configurations and other content types.

Batch Mode: generate multiple QR codes at once by adding entries manually or importing a CSV file.

Shared styling and output controls

Both modes support the same customisation options:

• Colour and style settings, including foreground/background colours, colour inversion, and module shape
• Optional center image overlay, automatically scaled and positioned to keep the QR code scannable
• Configurable output size and format (PNG, JPEG, BMP) for the final QR image
• Error correction level selection (Auto, L, M, Q, H) to control how damage resistant the QR code is
• Mask pattern selection to choose a visual pattern that suits your design or leave it on Auto to let the app pick the most scannable option

Note: When using a center image, the error correction level is automatically locked to High to ensure the QR code remains scannable.

Text Mode in detail

Text Mode is designed for creating a single QR code at a time, and supports a range of content types that QR scanners can recognise and automatically associate with the correct action.

Supported content types include:

• Text: plain text
• Website URL: opens a webpage when scanned
• Email: creates a pre-filled email with optional subject and message
• Phone Number: opens the phone app with the number ready to dial
• SMS: opens the messaging app with number and optional message filled in
• Wi‑Fi Configuration: lets devices join a Wi-Fi network (SSID, password, security type, hidden flag)
• Coordinates: opens the location in a maps app
• Contact (vCard): saves a contact with name, phone, email, website, and notes
• Calendar Event: adds an event with title, time, location, and notes

Text Mode Interface

Batch Mode in detail

Batch Mode supports two ways of adding entries:

• Add entries to a list manually
• Import a CSV document to populate the list

Batch Mode also provides two image file naming options:

• Base Name: you provide a base name and each image is saved with an incrementing index (e.g. 001_basename.png)
• Entry Text: uses the first 10 letters of the entry text, combined with an index (e.g. 001_DeskLamp.png)

Note: When using entry text for naming, the text is sanitised to ensure filenames are safe on all operating systems.

Batch Mode Interface

Under the hood

This application includes a custom QR encoder and renderer built to follow the QR Code specification (ISO/IEC 18004).
My goal was to be as faithful to the spec as possible, which at times proved a great but enjoyable challenge.

Encoder

Key behaviours include:

• Automatic mode selection
  Uses Numeric mode when possible for maximum efficiency, otherwise falls back to Byte mode (UTF-8) for all other text
• Automatic version selection (1-40)
  The encoder calculates the smallest QR version that can safely contain the data at the chosen error correction level
• Automatic error correction (L, M, Q, H)
  When set to Auto, the app selects the highest error correction level that still fits the data in the chosen version
• Full mask scoring implementation
  All eight QR mask patterns are generated and scored. The mask with the lowest penalty score is used when Auto is selected
• Deterministic matrix generation
  The same input always produces the same QR matrix for the same given text and error correction level, and the output has been verified against known working encoders

The encoder handles the full QR pipeline: mode selection, bitstream construction, padding, block formation, interleaving, matrix population, and mask scoring. The only part not implemented by hand is the Reed-Solomon error correction codeword generation, for which I opted to use a library to avoid polynomial chaos (see Credits & Thanks).

Renderer

• Pixel perfect rendering
  The matrix is first converted to an SVG at 1:1 scale, then upscaled and rasterised at the selected image size for best quality. This avoids fractional module sizes and prevents blurred, distorted output or thin background coloured lines appearing between dark modules
• Consistent styling
  Visual options such as module style and colours are applied after the matrix is finalised, so styling never alters the encoded data
• Safe area calculation for center images
  The renderer calculates a fixed safe region based on version, ensuring the QR remains scannable even with a logo present

Developer Mode

During development I often had no practical way to verify the intermediate stages of the QR encoding pipeline, especially for higher version QR codes where interleaving and block structure becomes complex.

For this reason, I decided to include a mode that exposes the output of the pipeline at every major step in the encoding process. It is intended for anyone who wants to study, debug, or validate QR encoding.

Developer Mode can be enabled from the Tools menu, and its features are as follows.

Version & Error Correction Selection

The encoder selects the smallest QR version that can hold the data. Versions are tested from lowest to highest.

If error correction is set to Auto, each version is tested with EC levels from highest to lowest (H → Q → M → L). The first version/EC combination that fits the data is selected.

Mask Selection & Scores

When mask selection is set to Auto, all 8 masks are evaluated and their penalty scores displayed. The mask with the lowest total penalty is selected.

Note: Mask scores may differ from other encoders due to differences in how evaluation conditions are implemented.
My approach was to be as accurate to the QR Code specification as possible. If you're curious about the exact scoring logic, the mask evaluation code is located in qr_matrix_generator.py.

Debug Tabs Overview

A detailed breakdown of each major step of the matrix generation pipeline starting from the initial bitstream to the final QR matrix. You can copy or compare values with your own outputs.

• Pre‑Codeword Bitstream (String)

  • A binary string containing mode bits, character count bits, encoded data, terminator bits, byte alignment padding, and alternating pad bytes up to the version's data capacity.

• Data Codewords (Python List Format)

  • The sequence of data codewords generated from the bitstream will be displayed here.

• Data Blocks (Python List of Lists Format)

  • Data codewords are split into blocks according to the QR version and error correction level.

• Error Correction Blocks (Python List of Lists Format)

  • Reed-Solomon error correction codeword blocks generated for each data block. Each data block corresponds to the error correction block at the same index.

• Final Bitstream (String)

  • The binary string of the final bitstream after interleaving the data and error correction codeword blocks and appending the required remainder bits for the selected version.

• Unmasked Matrix (Python List of Lists Format)

  • Displays the unmasked matrix with all functional patterns and data modules placed, with reserved values (default None) for the format and version bit information areas.
  • Reserved areas (format and version information) are filled with the value you specify in the Reserved Matrix Value field to better facilitate a comparison with your matrix.

• Final Matrix (Python List of Lists Format)

  • The final matrix with the selected mask, format/version bits placed, used for rendering.

Developer Mode Interface

Notes

A key lesson from this project was how important a strict modular design is when implementing a multi-stage specification.

Breaking the pipeline into clear, verifiable stages made debugging and validation dramatically easier.

Getting Started

Running the Application

• Requires Python 3.10 or later.
• Clone the repository to your machine.
• Navigate into the project folder.
• Install the required dependencies using pip install -r requirements.txt.
• Run the application using python main.py.

Packaging

The application can be packaged into an executable using PyInstaller or Nuitka. Both are supported by the app's path‑resolution logic. However Nuitka is recommended for performance.

The application is cross‑platform by design and should run on Windows, Linux, and macOS. However, macOS packaging isn't documented here as I don't have access to macOS hardware to test or confirm the builds.

Run the following command from the project folder:

Windows:

Nuitka (tested):

python -m nuitka --standalone --enable-plugin=pyside6 --windows-console-mode=disable --windows-icon-from-ico=resources/icons/qr-icon.ico --include-data-dir=resources=resources --output-filename=QRCodeMaker.exe --output-dir=build main.py

PyInstaller (tested):

pyinstaller --name=QRCodeMaker --noconsole --icon="resources/icons/qr-icon.ico" --add-data "resources/*;resources" main.py

Linux:

Nuitka (tested):

python -m nuitka --standalone --enable-plugin=pyside6 --include-data-dir=resources=resources --linux-icon=resources/icons/qr-icon.png --output-filename=QRCodeMaker --output-dir=build main.py

PyInstaller (tested):

python -m PyInstaller --name=QRCodeMaker --noconsole --icon="resources/icons/qr-icon.png" --add-data "resources/*:resources" main.py

Credits & Thanks

• Reed-Solomon error correction provided by the reedsolo Python library.
• The excellent QR Code tutorial by Thonky, which was invaluable for understanding the specification.
• Application icon sourced from UXWing.