pycrc

pycrc is a free, easy to use Cyclic Redundancy Check (CRC) calculator and C source code generator.

System Requirements

Python 3.10 or newer is required to run pycrc. The last version compatible with Python 2 is v0.9.x.

Running pycrc

The easiest way to run pycrc is to install it in a virtual environment, e.g.:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install pycrc

Then the pycrc executable is included in the path in the virtual environment:

pycrc [OPTIONS]

or

python3 -m pycrc [OPTIONS]

Installation

Install pycrc (if required) using pip:

python3 -m pip install pycrc

or apt (on Debian 13 and later, Ubuntu 23.10 and later, and derivatives):

sudo apt install pycrc

Either of these will install a pycrc binary in the path.

Once installed you can also run it as a module:

python3 -m pycrc [OPTIONS]

Python API

pycrc can also be used as a Python library:

import pycrc

# One-shot checksum for a named model.
print(pycrc.crc("crc-32", b"123456789"))

from pycrc import Crc

# Or use a model directly, choosing one of the algorithms.
crc = Crc.from_model("crc-16-usb")
print(crc.bit_by_bit_fast("123456789"))
print(crc.table_driven(b"123456789"))

# Large inputs can be processed incrementally.
crc = Crc.from_model("crc-32")
with open("image.bin", "rb") as f:
    for chunk in iter(lambda: f.read(4096), b""):
        crc.update(chunk)
print(crc.digest())

The known models are exposed as a read-only mapping:

from pycrc import CrcModels

models = CrcModels()
print(", ".join(models.names()))
params = models["crc-32"]
print(params.width, hex(params.poly), params.check)

The package ships inline type annotations (PEP 561), so editors and type checkers can use them without any extra stub packages.

Backwards compatibility

The Python API is additive: the API that existed before the typed models is still available.

• CrcModels.get_params() still returns a mutable dict (a copy); the immutable CrcParams objects are available through the mapping interface (models[name] / models.get(name)).
• Crc.tbl_idx_width and Crc.gen_table() remain available as aliases for Crc.table_idx_width and Crc.table.

Development

Create a virtual environment and install the package in editable mode together with the development tools:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e ".[dev]"

Running the tests

Run the whole test suite with pytest:

pytest

The tests in test/test_codegen.py and test/test_cli.py generate C source code, compile it and run it, so a C compiler (cc) must be installed and available on the PATH.

To run a single test file, class or function, pass it to pytest:

pytest test/test_algorithms.py
pytest test/test_codegen.py::TestCodeGen
pytest test/test_algorithms.py::test_all_models_with_check_input

To measure test coverage (and enforce the minimum coverage configured in pyproject.toml):

pytest --cov=pycrc --cov-report=term-missing

The code generation and CLI tests spawn subprocesses. To include the code that runs in those subprocesses in the coverage report, point COVERAGE_PROCESS_START at pyproject.toml, as the CI workflow does:

COVERAGE_PROCESS_START="$PWD/pyproject.toml" pytest --cov=pycrc --cov-report=term-missing

Checking the code style and types

ruff check .
mypy

Building the documentation

The HTML manual and the man page are generated from the DocBook source in doc. On Debian/Ubuntu the required tools are installed with:

sudo apt-get install make xsltproc docbook-xsl-ns docbook5-xml

Generate the documentation with:

make -C doc

This writes doc/pycrc.html, doc/pycrc.1 and the stylesheet doc/docbook.css. These generated files are not checked in.

Build the source and wheel distributions with:

python3 -m build

The sdist target regenerates the documentation and includes the generated files in the source tarball.

Getting help

If you are new to pycrc and want to generate C code, start with the tutorial.

The pycrc manual page explains the command line options in some detail and also gives some more examples how to use pycrc.

If you have found a bug in pycrc or want to request a feature please take the time and submit it to the issue tracker. Thanks for your help.

Also see the frequently asked questions.

Feedback

If you like pycrc, let me know and drop me a note. If you don't like pycrc let me know what you don't like and why. If you want some idea how to say thanks for this software, please have a look here.

Copyright of the generated source code

The MIT licence allows commercial use of the source and the output of the program. But since I got asked on occasion whether the generated code is encumbered by the copyright of the author, I give my view on this:

The code generated by pycrc is not considered a substantial portion of the software, therefore the licence does not cover the generated code; the author of pycrc will not claim any copyright on the generated code.