Install & Compatibility
Where this runs
tested against v0.1.9 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 37.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.000s · 39MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
decode
✓ from pyzbar.pyzbar import decode
✗ import pyzbar; pyzbar.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.
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}")
Debug
Known issues
gotchaOn 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.fixInstall `zbar` using your system's package manager (e.g., `brew install zbar` on macOS, `sudo apt-get install libzbar0` on Debian/Ubuntu).
affects: All versions
gotchaOn 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.fixInstall the Visual C++ Redistributable Packages for Visual Studio 2013 (both x64 and x86 versions) relevant to your Python installation.
affects: All versions on Windows
gotchaWhen decoding images, the `decode` function should be imported from `pyzbar.pyzbar`. A common mistake is trying to call `pyzbar.decode()` directly.fixUse `from pyzbar.pyzbar import decode` for the correct import path.
affects: All versions
gotchaThe `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.fixCall `.decode('utf-8')` on the `data` attribute, for example: `barcode.data.decode('utf-8')`. affects: All versions
gotchaThe `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.fixUpdate your `zbar` shared library to a newer version that supports orientation if this feature is critical for your application.
affects: Older zbar library installations
Upgrade
Version history
0.1.9latest on PyPI · released Mar 15, 2022
Audit
Dependencies
zbarrequiredpyzbar is a Python wrapper for the zbar C library, which must be installed separately on non-Windows systems.
PillowoptionalRequired for image processing when using PIL/Pillow Image objects, and for command-line scripts.
opencv-pythonoptionalRequired for image processing when using OpenCV/NumPy ndarrays.