← Articles

pyzbar does not read DataMatrix: how to read GS1 DataMatrix in Python

A common answer to “how do I read a DataMatrix code in Python” is pyzbar. It will not work: ZBar, the library behind it, does not support DataMatrix at all. Worse, there is no error — decode() returns an empty list, and it looks as if the image were the problem. Below is what does work, tested on the same GS1 DataMatrix code.

Experiment: one code, four libraries

The code is a GS1 DataMatrix with FNC1 and a GS separator, as printed on packaging: (01)04601234567893(21)5Abc12Xyz!-(93)dGVz. The image is 208×208 pixels, clean, no noise. Python 3.13.

LibraryResultWhat matters
pyzbar 0.1.9empty listDataMatrix is not supported; no error is raised
pylibdmtx 0.1.10read, GS keptfails to import on Python 3.12+ without setuptools (needs the distutils module)
zxing-cpp 3.1.1read, flagged as GS1take the string with GS from bytes, not from text
dmr 1.2.4 (libscanner)read, GS keptbuilt for industrial camera frames on a production line

pyzbar: why the result is empty

ZBar reads EAN/UPC, Code 128, Code 39, Code 93, Codabar, Interleaved 2 of 5, DataBar and QR. DataMatrix is not on the list, so no setting will help:

from pyzbar import pyzbar
from PIL import Image

print(pyzbar.decode(Image.open("cz.png")))
# []

pylibdmtx: works, but check your Python version

pylibdmtx wraps libdmtx. It reads the code and keeps the GS separator (byte 29). Its latest release, however, imports distutils, which was removed from the standard library in Python 3.12, and fails with ModuleNotFoundError: No module named 'distutils'. Installing setuptools fixes it:

# pip install pylibdmtx setuptools
from pylibdmtx import pylibdmtx
from PIL import Image

print(pylibdmtx.decode(Image.open("cz.png"))[0].data)
# b'0104601234567893215Abc12Xyz!-\x1d93dGVz'

zxing-cpp: free and reliable, but do not mix up text and bytes

The zxing-cpp package (Apache 2.0) reads DataMatrix, QR and linear codes and detects GS1 by itself. The trap: text is the human-readable string, with parentheses around Application Identifiers and no GS. ERP systems and marking-system checks need the string with GS, which is in bytes:

# pip install zxing-cpp pillow
import zxingcpp
from PIL import Image

r = zxingcpp.read_barcodes(Image.open("cz.png"))[0]
print(r.content_type)  # ContentType.GS1
print(r.text)          # (01)04601234567893(21)5Abc12Xyz!-(93)dGVz
print(r.bytes)         # b'0104601234567893215Abc12Xyz!-\x1d93dGVz'

If you need to read a code from a photo or a scan now and then, zxing-cpp is enough — you do not need a paid library.

dmr: for a stream of camera frames on a line

dmr from libscanner solves a different problem: a conveyor, an industrial camera, thousands of frames per hour, small, blurred or tilted codes, and no tolerance for false reads. On a dataset of 8,959 production-line images it read 99.6% of frames with no false reads; the median time is 7 ms per frame on one core, JPEG decoding included.

# pip install libscanner-dmr
import dmr

scanner = dmr.Scanner()
r = scanner.scan(dmr.Image("cz.png", dmr.LoadAs.GRAY).view())
if r.ok:
    print(r.text)  # b'0104601234567893215Abc12Xyz!-\x1d93dGVz'

The library is commercial; for the first month on a machine it runs without a license and without network access, which is enough to test it on your own frames.

What to choose

  • Read a code from a photo or scan occasionally — zxing-cpp; take the GS string from bytes.
  • An existing project on pylibdmtx — keep it; on Python 3.12+ add setuptools.
  • A camera on a line, speed and zero false reads required — dmr; test it on your frames during the trial month.
  • pyzbar — for linear barcodes and QR only, not for DataMatrix.

What to do with the decoded string next — parse the fields and check the separators — is covered in the article on the GS separator and FNC1.

Try it

Check how your code reads from a photo in the online decoder — no installation or sign-up. dmr Python documentation is on the site; the package is libscanner-dmr on PyPI.

Chestny ZNAK is a trademark of CRPT LLC (ООО «Оператор-ЦРПТ»); GS1 is a trademark of GS1 AISBL. The product is not affiliated with or certified by their owners.