pyzbar

0.1.9 · maintenance · verified Sat Apr 11

pyzbar is a Python library that provides bindings for the open-source ZBar barcode reading library. It allows users to read one-dimensional barcodes and QR codes from various image sources, including PIL/Pillow images, OpenCV/NumPy ndarrays, and raw bytes. The current version is 0.1.9. While some sources suggest active maintenance and regular updates, external analysis indicates an inactive maintenance status with no new PyPI releases in the past 12 months as of late 2025.

Warnings

gotcha On non-Windows operating systems (macOS, Linux), the underlying `zbar` shared library must be installed separately from `pyzbar`. `pyzbar` itself is just a Python wrapper. Failure to install `zbar` will result in an `ImportError` or 'Unable to find zbar shared library' error.
Fix: Install `zbar` using your system's package manager (e.g., `brew install zbar` on macOS, `sudo apt-get install libzbar0` on Debian/Ubuntu).
gotcha On Windows, if you encounter an `ImportError` when importing `pyzbar`, it may be due to missing Visual C++ Redistributable Packages for Visual Studio 2013. This is especially true if `libiconv.dll` or `libzbar-64.dll` (or 32-bit equivalents) are not found, even if they appear to be present.
Fix: Install the Visual C++ Redistributable Packages for Visual Studio 2013 (both x64 and x86 versions) relevant to your Python installation.
gotcha When decoding images, the `decode` function should be imported from `pyzbar.pyzbar`. A common mistake is trying to call `pyzbar.decode()` directly.
Fix: Use `from pyzbar.pyzbar import decode` for the correct import path.
gotcha The `data` attribute of the `Decoded` object (the barcode content) is a byte string (`bytes`). You need to explicitly decode it to a string (`str`) using a suitable encoding (e.g., `'utf-8'`) if you want to work with text.
Fix: Call `.decode('utf-8')` on the `data` attribute, for example: `barcode.data.decode('utf-8')`.
gotcha The `orientation` field of the `Decoded` object might be `None` if your installed `zbar` library is an older release (pre-2019 fork) that does not support decoding barcode orientation.
Fix: Update your `zbar` shared library to a newer version that supports orientation if this feature is critical for your application.

Install

pip install pyzbar Standard Installation
pip install pyzbar[scripts] Installation with command-line script dependencies (e.g., Pillow)
brew install zbar macOS (install zbar shared library)
sudo apt-get install libzbar0 Linux (install zbar shared library)

Imports

decode
```
from pyzbar.pyzbar import decode
```
The `decode` function is located within the `pyzbar.pyzbar` submodule, not directly under `pyzbar`.
ZBarSymbol
```
from pyzbar.pyzbar import ZBarSymbol
```
Used to specify particular barcode types to decode.

Quickstart

This quickstart demonstrates how to use `pyzbar` to decode barcodes from an image using the Pillow library. It opens an image file and then calls the `decode` function to extract barcode information, printing the decoded data and type. Remember to replace `image_path` with the actual path to your barcode image.

from pyzbar.pyzbar import decode
from PIL import Image
import os

# Assuming an image file named 'barcode.png' exists in the current directory
# For a real application, replace with a path to your image or a file handle
image_path = os.environ.get('PZ_TEST_IMAGE_PATH', 'pyzbar/tests/code128.png') # Using a test image from the repo for runnable example

try:
    # Open the image file using Pillow
    img = Image.open(image_path)

    # Decode any barcodes in the image
    barcodes = decode(img)

    if barcodes:
        for barcode in barcodes:
            print(f"Decoded Data: {barcode.data.decode('utf-8')}")
            print(f"Barcode Type: {barcode.type}")
            print(f"Location (Rect): {barcode.rect}")
    else:
        print("No barcodes found in the image.")

except FileNotFoundError:
    print(f"Error: Image file not found at {image_path}. Please provide a valid path.")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →