Canmatrix: one object model for every CAN database format your supplier ships

One object model sits under a dozen file formats

Canmatrix is a Python package to read and write several CAN database formats. The stated purpose is narrow and practical: implement a Python Can Matrix Object which describes the can-communication and the needed objects, namely board units, frames, signals, and values.

That object model is the design. Every format in the import list is parsed into the same structure of board units, frames, signals, and values, and every export format is written from it. A team that receives a Vector.dbc from one supplier, a Kayak.kcd from another, and an AUTOSAR.arxml from a third can hold all three in one representation and write any of them back out.

The import list is long, and each entry names the tool that produces it:.dbc for candb and Vector,.dbf for Busmaster,.kcd for Kayak,.arxml for autosar system description,.yaml as a structured export and import with the same structure as json,.xls(x) for Excel import which works with the.xls file generated by this library,.sym for peak pcan can description,.xml for fibex or CANopen eds,.ldf for the lin bus,.odx for diagnostic files, and.eds.

Two of those are marked open source in the list, which tells you the project takes interoperability with free tools seriously rather than only with commercial ones. The.xls(x) support is also symmetric, since the library can write the Excel files it can read.

The export list is shorter but covers a different set of consumers:.dbc,.dbf,.kcd,.xls(x),.json for Canard,.arxml,.yaml,.sym,.xml for fibex,.lua as a Wireshark script, and.scapy. The.lua and.scapy exports are the interesting ones, because they turn a communication matrix into something a network analysis tool can read.

Two console scripts cover conversion and comparison

The package installs two command line entry points, declared in pyproject.toml:

[project.scripts]
cancompare = "canmatrix.cli.compare:cli_compare"
canconvert = "canmatrix.cli.convert:cli_convert"

The project summary describes them as two tools for converting and comparing CAN databases, and the console script classifier is Environment :: Console, so the CLI is a first class entry point rather than a wrapper around the library.

The division of labour is obvious from the names and worth spelling out. `canconvert` handles format translation, which is the operation most teams need most often: a database arrives in one format, a tool downstream needs another. `cancompare` handles diffing, which is the operation that matters when the same matrix has been edited by two people or two tools and you need to know what changed before merging.

A diff tool over a normalised object model is more useful than a text diff over a file, because the formats are not line-oriented in a comparable way. Two .dbc files that differ only in ordering of signals are textually different and semantically identical, and a comparison that goes through the object model can say so. The library also offers programmatic encode and decode of CAN messages, which the project lists as a capability alongside format parsing, and the examples directory contains `encodeFrame.py` and `decodeFrame.py` for exactly that.

The dependency list is short: attrs, click, and two conditional shims for importlib-metadata and typing on old Python versions. The CLI is built on click, which is why the package can be installed with a single `pip install` and still give you a usable command line.

The examples directory shows the library used as a library

The repository carries a substantial `examples/` directory, and reading it tells you more about the intended usage than the format list does.

There are two script pairs that match the two tools. `examples/convert.py` and `examples/compare.py` are the programmatic equivalents of `canconvert` and `cancompare`, so you can see what the CLI does under the hood. There is also `examples/exampleJoin.py` and `examples/exampleMerge.py`, which are operations the CLI names do not obviously cover, joining and merging matrix files.

Then there are format-specific and domain-specific scripts. `examples/createJ1939Dbc.py` and `examples/j1939_test.py` deal with the J1939 standard used in heavy vehicles. `examples/createccl.py` generates a CCL file, and `examples/createCMacros.py` creates a macro file. `examples/cmTemplate.xlsx` is a template spreadsheet, which pairs with the.xls(x) import and export support.

`examples/dissect_cannelloni.lua` is a Wireshark dissector written in Lua, and it is the same idea as the.lua export. A CAN matrix describes frames and signals, and a Wireshark dissector can use that description to decode captured traffic into readable field values. Writing the dissector in Lua means it runs inside Wireshark, with no Python runtime in the loop.

`examples/fr_dump.py` handles the unglamorous part of the job, dumping a file, and `examples/decodeFrame.py` and `examples/encodeFrame.py` are the round trip for building and reading a frame from its signal values.

For a team deciding whether this library fits, this directory is the best single piece of evidence, because it shows the library being used the way you would use it.

AUTOSAR support is the one that is explicitly basic

The export list contains a caveat that belongs in any evaluation:.arxml is marked as a very basic implementation, while the import side lists.arxml as autosar system description without that qualifier.

That asymmetry is the single most important limitation in the project. AUTOSAR system descriptions are the format of choice for large automotive programmes, and they are substantially more structured than a.dbc or a.kcd. A basic export means the round trip is lossy in a way the other formats are not, and a lossy round trip on a communication matrix is dangerous, because the thing you lose is usually the part a downstream tool wanted.

The other formats are more reassuring by comparison. The.dbc,.dbf,.kcd,.sym, and.xls(x) paths are all in both lists, which means they are exercised in both directions. The.yaml path is the project's own structured representation, and since the.yaml entry is described as the same structure as json, that is the format to use when you want a lossless intermediate that you can diff and merge by hand.

The.xml entry is worth a note too, since the same extension appears twice with different meanings. On import,.xml covers fibex or CANopen eds, and on export,.xml covers fibex. So the import side is broader than the export side, which is consistent with the pattern that the project reads more than it writes perfectly.

The.scapy export is another one to check against your toolchain, because Scapy is a network crafting tool and the.scapy output is presumably a script rather than a data file, but the summary does not describe it further, so anyone planning to use it should check the output rather than assume.

A mature package with a multi-file contributor workflow

The project metadata describes itself as Development Status :: 5 - Production/Stable, and the release history supports reading that as a stable library rather than an experimental one. Versions 1.0 in November 2023, 1.1 in February 2025, and 1.3 in October 2026 show a project that ships on a slow, deliberate cadence and does not churn major versions.

The contributor instructions are unusually concrete, and they are written as a numbered list of literal commands:

git checkout -b feature/AmazingFeature
git commit -m 'Add some AmazingFeature'
git push origin feature/AmazingFeature

Fork the project, create a feature branch, commit, push, open a pull request. The project states that source code, documentation, examples, issue reports, and any other contributions are extremely appreciated.

The repository structure supports a fairly serious engineering setup. There is a `src/` layout, `tests/`, `stubs/` for type stubs, a `mypy.ini` at the root, a `tox.ini`, a `.coveragerc`, an `appveyor.yml` for Windows CI, a `requirements_docs.txt`, and a `docs/` directory. The presence of `stubs/` and `mypy.ini` together says the library is typed and checked, and the `tox.ini` alongside `appveyor.yml` says the test matrix runs on more than one platform and more than one interpreter.

The default branch is `development`, not `main`, and the last push to the repository was on 2026-10-06. The licence is BSD-2-Clause, recorded in pyproject.toml with a matching OSI-approved classifier, and the maintainer field reads canmatrix contributors rather than a single named person, which fits a project of this age and scope.

Where Canmatrix is the wrong tool

The boundaries are clear enough to state directly.

First, this is not an AUTOSAR toolchain. If your deliverable is a complete AUTOSAR system description with the layering, ports, and data types that real programme work requires, the very basic .arxml export will not get you there, and the project does not claim it would. The right tool for that is a dedicated AUTOSAR authoring environment, and Canmatrix is the tool to move data in and out of such an environment rather than the tool that produces it.

Second, Canmatrix is a database and codec library, not a network tool. It does not sit on a bus, it does not trace, and it does not schedule frames. If you need to see what is actually on the wire, you want a bus analyser or a dissector, and Canmatrix's value there is that it can generate the .lua dissector from the same matrix your team maintains.

Third, the decode path is where care is needed. Encoding and decoding a frame means interpreting bit positions, byte order, and scaling against signal definitions, and a matrix that came from a supplier with an unusual encoding convention can decode to plausible but wrong values. The library is a faithful reader of the format, and it is not a validator of the matrix against the bus.

Fourth, the version cadence is slow, which is a feature and a constraint. A 1.0 to 1.3 progression over three years means the API is stable and the project is not going to change under you. It also means that if a format or a feature you need is missing, there is no quick fix, and the sensible move is to file the issue through the pull request workflow rather than expect a release soon.

Finally, the environment matters. The package requires Python 3.8 or newer and is tested against 3.8 through 3.13, so a team on an older interpreter is out of luck, and the Windows support implied by the appveyor configuration and the Windows classifier means the tool is expected to run on the same machines as the engineering tools it complements.

Editorial conclusion

Canmatrix fits an automotive or embedded team whose CAN database arrives in whatever format a supplier happened to use, and who needs to convert, diff, or decode it without maintaining one parser per format. It is the wrong tool if you need a full AUTOSAR toolchain, because the .arxml support is described as a very basic implementation. Check three things before you adopt it: which of your incoming formats are on the import list, since .arxml is explicitly basic while the .dbc and .kcd paths are mature, whether the export side covers what your downstream tools consume, and that the Python version fits, since the package requires Python 3.8 or newer and is tested against 3.8 through 3.13.

Frequently asked questions

Official sources

1. ebroecker/canmatrix on GitHub
2. Issues
3. License: BSD-2-Clause
4. README
5. Releases