Registry / serialization / zxing-cpp

zxing-cpp

JSON →
library3.0.0pypypi✓ verified 85d ago

zxing-cpp provides Python bindings for the high-performance C++ port of the ZXing barcode library. It supports reading and writing a wide range of 1D and 2D barcode formats like QR Code, Data Matrix, UPC-A, and Code 128. The current version is 3.0.0, and it maintains an active development and release cadence, typically tied to its underlying C++ library.

pip install zxing-cpp
INSTALL
IMPORT
SIG · ZXING-CPP
Z
zxing-cpp
serializationpythonv3.0.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
4/8 runs
py 3.11
✕ build_error
4/8 runs
py 3.12
✕ build_error
4/8 runs
py 3.13
✕ build_error
4/8 runs
py 3.9
✕ build_error
✕ build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

zxingcpp
import zxingcpp
BarcodeFormat
from zxingcpp import BarcodeFormat
read_barcodes
import zxingcpp # ... barcodes = zxingcpp.read_barcodes(image_data)
create_barcode
import zxingcpp # ... barcode = zxingcpp.create_barcode(text, zxingcpp.BarcodeFormat.QRCode)

This quickstart demonstrates how to both read and write barcodes using `zxing-cpp`. Reading typically involves loading an image with OpenCV (`cv2`) and passing it to `zxingcpp.read_barcodes`. Writing involves creating a barcode object with `zxingcpp.create_barcode`, converting it to an image array, and saving it using a library like Pillow (`PIL`).

import zxingcpp import cv2 from PIL import Image import numpy as np # --- Example 1: Reading a barcode from an image (requires OpenCV) --- # Create a dummy image with a QR code (in a real scenario, load from file) # For demonstration, we'll generate one and save it def generate_and_save_qr_code(text, filename="test_qr.png"): barcode_obj = zxingcpp.create_barcode(text, zxingcpp.BarcodeFormat.QRCode, ec_level="50%") img_array = barcode_obj.to_image(scale=5) Image.fromarray(img_array).save(filename) print(f"Generated '{filename}' for reading example.") qr_text = "Hello, zxing-cpp!" generate_and_save_qr_code(qr_text) # Read the generated image img = cv2.imread('test_qr.png') if img is not None: results = zxingcpp.read_barcodes(img) if results: for result in results: print(f"\nFound barcode (read):\n Text: '{result.text}'\n Format: {result.format}\n Position: {result.position}") else: print("\nCould not find any barcode in test_qr.png.") else: print("\nError: Could not load test_qr.png for reading.") # --- Example 2: Writing a barcode to an image (requires Pillow) --- text_to_encode = "This is a test from zxing-cpp Python!" barcode_format = zxingcpp.BarcodeFormat.DataMatrix try: # Create a barcode object barcode = zxingcpp.create_barcode( text_to_encode, barcode_format, ec_level="L" # For DataMatrix, 'L' is a common error correction level ) # Convert the barcode to a NumPy array image img_array = barcode.to_image(scale=2) # Scale up for better visibility # Convert NumPy array to PIL Image and save pil_img = Image.fromarray(img_array) output_filename = "output_barcode.png" pil_img.save(output_filename) print(f"\nSuccessfully wrote {barcode_format} barcode to '{output_filename}'") # Optionally, convert to SVG string svg_string = barcode.to_svg(add_quiet_zones=True) svg_filename = "output_barcode.svg" with open(svg_filename, "w") as f: f.write(svg_string) print(f"Successfully wrote {barcode_format} barcode to '{svg_filename}'") except Exception as e: print(f"\nError writing barcode: {e}")
Debug
Known issues
breakingVersion 3.0.0 introduced significant changes to the creator/writer API, including `BarcodeFormat` and `BarcodeFormats` implementations. The old writer API (`write_barcode`) is now deprecated and `create_barcode` is the default.
fix
Update barcode creation and writing code to use the new `create_barcode` API and the updated `BarcodeFormat` and `BarcodeFormats` classes as shown in the quickstart example. Refer to the official README for details.
affects: >=3.0.0
breakingBuilding `zxing-cpp` from source now explicitly requires a C++20 compliant compiler (e.g., GCC 11+, Clang 12+, VS 2019 16.10+) and CMake 3.18 or newer for the Python module. Without pre-built wheels, this can cause build failures.
fix
Ensure your development environment meets the C++20 compiler and CMake version requirements if you are building `zxing-cpp` from source or using the `--no-binary zxing-cpp` installation option.
affects: >=3.0.0
gotchaWhen reading images, especially from file paths, ensure the path is correct and accessible. `FileNotFoundError` is a common issue, particularly on Windows where path separators (`\` vs `/`) or relative vs. absolute paths can cause problems.
fix
Always verify file paths using `os.path.exists()` or convert to absolute paths with `os.path.abspath()`. Use raw strings (`r'C:\path\to\file'`) or forward slashes (`'C:/path/to/file'`) for consistency on Windows.
affects: All versions
gotcha`zxing-cpp` is highly optimized for single barcode detection but may struggle with images containing multiple barcodes, exhibiting lower success rates compared to some other libraries in such scenarios.
fix
If your application frequently processes images with many barcodes, consider pre-processing the image to isolate individual barcodes, or evaluate alternative libraries if multi-barcode detection is critical and `zxing-cpp`'s performance is insufficient for your specific use case.
affects: All versions
Errors
Common errors & fixes
FileNotFoundError: [WinError 2] The system cannot find the file specified
The image file specified in `cv2.imread()` or similar image loading function does not exist at the given path or is inaccessible.
fix
Double-check the file path. Use an absolute path or ensure your relative path is correct from the script's current working directory (`os.getcwd()`). On Windows, ensure path separators are handled correctly (e.g., `r'C:\path\image.png'` or `'C:/path/image.png'`).
Could not find any barcode.
The `read_barcodes` function returned an empty list, indicating no barcode was detected. This can be due to poor image quality (blur, low resolution, bad lighting, shadows, angle), an unsupported barcode format, or the barcode being too small/damaged.
fix
Improve image quality (ensure good lighting, focus, contrast). Try rotating or downscaling the image before passing it to `read_barcodes`. Ensure the barcode format is one of the supported types by `zxing-cpp`. For critical cases, inspect image binarization/thresholding parameters or consider `try_rotate` and `try_downscale` options in `read_barcodes` for more robust detection.
AttributeError: 'Barcode' object has no attribute 'some_attribute'
Attempting to access a non-existent attribute on the `Barcode` result object. This often happens if users expect a different data structure for properties like 'position' (e.g., direct x,y tuples instead of a string representation) or misremember attribute names.
fix
Consult the `zxing-cpp` documentation or the `PYBIND11_MODULE` definition in the C++ source for the exact properties and their types on the `Barcode` object. For position, it's typically a string that needs parsing if numerical coordinates are required. Common attributes include `text`, `format`, `content_type`, `position`.
Upgrade
Version history
3.0.0latest on PyPI · released Feb 10, 2026
Audit
Dependencies
PillowoptionalCommonly used for image handling, especially when writing barcodes.
opencv-pythonoptionalCommonly used for image handling, especially when reading barcodes.
C++20 compilerrequiredRequired for building from source if pre-built wheels are not available.
CMake >=3.18requiredRequired for building the Python module from source.
Agent activity
71 hits · last 30 days
node
64
OpenAI (training)
1
Resources