PyZXing

1.1.1 · active · verified Thu Apr 16

PyZXing is a Python wrapper for the popular ZXing Java library, providing functionality primarily for decoding 1D and 2D barcodes (like QR codes) from image files or in-memory image bytes. It currently stands at version 1.1.1 and has an irregular release cadence, largely driven by updates to the underlying ZXing Java core.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'java'
```
cause The Python interpreter could not find the 'java' executable in the system's PATH, which is required to run the underlying ZXing Java library.

fix Ensure a Java Runtime Environment (JRE) is installed and its 'bin' directory is added to your system's PATH environment variable. Alternatively, instantiate `BarCodeReader` with the full path to the `java` executable, e.g., `BarCodeReader(java_path='/usr/bin/java')`.
```
java.lang.NoClassDefFoundError: com/google/zxing/MultiFormatReader
```
cause The ZXing core JAR file required by `pyzxing` is either missing, corrupted, or not properly located by the Java process. This can happen if the PyZXing installation is incomplete or environment variables interfere.

fix Reinstall `pyzxing` (`pip install --force-reinstall pyzxing`). If the issue persists, check for any `CLASSPATH` environment variables that might be overriding the internal one used by `pyzxing`.
```
java.io.FileNotFoundException: <image_file_path> (No such file or directory)
```
cause The image file specified for decoding does not exist at the given path, or the path is incorrect/inaccessible by the Java subprocess.

fix Verify that the `image_file_path` passed to `reader.decode()` is correct and that the Python process has read permissions for that file and directory. Ensure there are no typos in the file path.
```
No barcode found in <image_file_path>
```
cause PyZXing successfully processed the image but could not detect any valid barcodes. This is not an error in the library's execution, but rather in the content of the image.

fix Ensure the image contains a clear, high-contrast barcode. Check for image quality, resolution, rotation, and lighting conditions. Try decoding different images known to contain barcodes to rule out image-specific issues.

Warnings

gotcha PyZXing is a wrapper around a Java library. A Java Runtime Environment (JRE) must be installed and accessible via your system's PATH for PyZXing to function correctly.
Fix: Install a JRE (e.g., OpenJDK) for your operating system and ensure the `java` executable is in your system's PATH, or specify its path via the `java_path` argument to `BarCodeReader`.
gotcha The `pyzxing` library primarily focuses on barcode *decoding*. While the underlying ZXing Java library supports encoding, this Python wrapper does not directly expose encoding functionality through its public API.
Fix: For barcode encoding, consider using other Python libraries designed for encoding (e.g., `qrcode` for QR codes) or directly calling the ZXing Java library if encoding is a critical requirement.
gotcha PyZXing executes the Java ZXing library as a subprocess. This can introduce overhead, making it less suitable for high-performance, low-latency barcode processing tasks compared to pure Python or C/C++ based solutions.
Fix: Evaluate performance requirements. For extremely high-throughput scenarios, consider alternatives or pre-processing images to reduce the number of `pyzxing` calls. Ensure adequate system resources and an efficient JRE installation.
gotcha If you don't provide a valid `java_path` to the `BarCodeReader` constructor, PyZXing relies on the `java` executable being found in your system's PATH environment variable. If it's not found, you'll encounter a `FileNotFoundError`.
Fix: Either add your JRE's `bin` directory to your system's PATH, or initialize the reader with the explicit path to your Java executable: `reader = BarCodeReader(java_path='/path/to/your/java')`.

Install

pip install pyzxing Install PyZXing

Imports

BarCodeReader
```
from pyzxing import BarCodeReader
```

Quickstart

Initializes the BarCodeReader and attempts to decode a barcode from a specified image file. Note that `pyzxing` calls an external Java process, requiring a JRE installation. Results are returned as a list of dictionaries.

import os
from pyzxing import BarCodeReader

# For demonstration, create a dummy image file if it doesn't exist
# In a real scenario, 'barcode.png' would be an actual image with a barcode.
dummy_image_path = 'barcode.png'
if not os.path.exists(dummy_image_path):
    print(f"Warning: '{dummy_image_path}' not found. Decoding might fail. Please provide a real barcode image.")
    # Example of how you might create a dummy (non-barcode) file to prevent FileNotFoundError
    with open(dummy_image_path, 'w') as f:
        f.write('This is not an image.')

try:
    reader = BarCodeReader()
    # Decode from a file path
    results = reader.decode(dummy_image_path)
    if results:
        for result in results:
            print(f"Decoded text: {result.get('parsed', 'N/A')}")
            print(f"Format: {result.get('format', 'N/A')}")
    else:
        print(f"No barcode found in {dummy_image_path}")
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up dummy file if created for demonstration
    if not os.path.exists(dummy_image_path):
        os.remove(dummy_image_path)

view raw JSON →