pyzxing

English | 简体中文

Reliable Python bindings for the ZXing barcode decoder. pyzxing exposes a stable Python API while delegating decoding to a versioned, checksum-verified Java Runner.

Features

• Decode one image or a glob of images into one consistent result list.
• Read QR Code, Data Matrix, PDF417, Aztec, and common one-dimensional formats.
• Accept file paths and NumPy arrays.
• Preserve binary payloads, byte segments, result points, metadata, and orientation.
• Control ZXing with explicit format, charset, multi-code, and effort hints.
• Run on Linux, macOS, and Windows with Python 3.8–3.14 and Java 17+.
• Install a pinned Runner automatically, or receive it directly from conda-forge.

Requirements

Java must be available as java on PATH. The Python package downloads the matching Runner on first use and verifies its SHA-256 checksum. The conda-forge package installs that Runner inside the environment.

Installation

Install from PyPI:

python -m pip install pyzxing

Or install from conda-forge:

conda install -c conda-forge pyzxing

Quick start

from pyzxing import BarCodeReader

reader = BarCodeReader()
results = reader.decode("/path/to/qrcode.png")

for result in results:
    print(result["format"], result["text"])

Globs return the same flat list[dict] shape:

results = reader.decode("/path/to/images/*.png")

Pass decode hints explicitly when needed:

results = reader.decode(
    "/path/to/barcode.png",
    multi=True,
    try_harder=True,
    character_set="UTF-8",
    possible_formats=["QR_CODE", "DATA_MATRIX"],
)

NumPy arrays

Install OpenCV and pass an RGB or grayscale array:

python -m pip install opencv-python

results = reader.decode_array(image)

Results

Every decoded barcode is represented by a dictionary. The most commonly used fields are:

The legacy byte-valued raw and parsed fields remain available for backward compatibility. Use byte_segments for binary QR payloads instead of re-encoding text.

Documentation

The complete guide is available on Read the Docs:

• Installation and runtime requirements
• Usage and decode hints
• Result schema
• API reference
• PyInstaller and deployment
• Troubleshooting

Command-line examples

Scan a file:

python scripts/scanner.py -f /path/to/barcode.png

Sample frames from a webcam:

python -m pip install opencv-python
python scripts/webcam_demo.py --camera 0 --interval 0.5

The webcam example uses the existing one-shot decode_array() API. It does not keep a persistent Java process running.

Development

python -m pip install -e '.[dev]'
./mvnw -f java-runner/pom.xml clean verify
python -m pytest tests/

Use mvnw.cmd instead of ./mvnw on Windows. See the development guide for documentation builds and release checks.

Project links

• Documentation
• Changelog
• Releases
• Issue tracker
• License