Usage

Files and globs

BarCodeReader.decode() accepts a path or a glob pattern. Paths are expanded, made absolute, sorted, and decoded without invoking a shell. Missing matches raise FileNotFoundError.

reader.decode("invoice.png")
reader.decode("incoming/*.png")

Decode hints

The keyword-only hints map to explicit ZXing behavior:

multi

Search for multiple barcodes in each image. Defaults to True.

try_harder

Ask ZXing to spend more effort locating a barcode. Defaults to True.

pure_barcode

Treat the input as a clean monochrome barcode without surrounding content.

character_set

Supply a character-set hint when the symbol does not declare one.

possible_formats

Restrict decoding to ZXing BarcodeFormat names such as QR_CODE, DATA_MATRIX, PDF_417, AZTEC, CODE_128, or EAN_13.

results = reader.decode(
    "label.png",
    multi=False,
    try_harder=True,
    pure_barcode=False,
    character_set="UTF-8",
    possible_formats=["CODE_128", "QR_CODE"],
)

NumPy arrays

Install OpenCV to use decode_array():

python -m pip install opencv-python

The method accepts a grayscale array or an RGB array, writes a temporary PNG, and delegates to the same decode path:

results = reader.decode_array(image)

The temporary file is removed whether decoding succeeds or fails.

Errors and timeouts

JavaNotFoundError is raised during reader construction when Java is not on PATH. Runtime failures use DecodeError and preserve the Runner error code in exception.code. DecodeTimeoutError and FileTooLargeError identify timeout and size-limit failures explicitly.