Install & Compatibility
Where this runs
tested against v1.2 · 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.915 runs
installs and imports cleanly · install 0.0s · import 0.238s · 23.1MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 1.8s · import 0.214s · 24MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CanMatrix
✓ from canmatrix import CanMatrix
The main object representing a CAN database.
dbc_load
✓ from canmatrix.formats import dbc
For loading DBC files; other formats are similarly available under `canmatrix.formats` (e.g., `arxml`, `kcd`).
dbc_dump
✓ from canmatrix.formats import dbc
For dumping (saving) DBC files; other formats are similarly available under `canmatrix.formats`.
cli_convert
✓ from canmatrix.cli import convert
✗ import canmatrix.convert
CLI tools like `convert` and `compare` were moved to the `canmatrix.cli` submodule in version 0.8.
This quickstart demonstrates how to load a CAN database (DBC file) into a `CanMatrix` object, then iterate through its frames and signals to access their properties. A dummy DBC file is created for a runnable example.
import os
from canmatrix.formats import dbc
# Create a dummy DBC file for demonstration
dummy_dbc_content = '''
BO_ 100 MSG_1: 8 Vector__XXX
SG_ Sig1 : 0|8@1+ (1,0) [0|255] "" Vector__XXX
SG_ Sig2 : 8|16@1+ (0.1,0) [0|6553.5] "" Vector__XXX
'''
dbc_file_path = 'dummy.dbc'
with open(dbc_file_path, 'w') as f:
f.write(dummy_dbc_content)
# Load the CAN matrix from the DBC file
db = dbc.load(dbc_file_path)
# Access frames and signals
for frame_name in db:
frame = db.frames[frame_name]
print(f"Frame: {frame.name} (ID: {frame.arbitration_id.id}, DLC: {frame.size} bytes)")
for signal_name in frame.signals:
signal = frame.signals[signal_name]
print(f" Signal: {signal.name} (StartBit: {signal.start_bit}, Length: {signal.size} bits)")
# Clean up the dummy file
os.remove(dbc_file_path)
canconvert --version
Debug
Known issues
breakingMajor internal refactoring and module reorganization in versions leading up to 1.0 (specifically around 0.8 and 0.9) introduced breaking changes. Direct imports of modules like `canmatrix.convert` or `canmatrix.formats.<format>` from earlier versions (pre-0.8) are likely to fail, as many components were moved to `canmatrix.cli` and `canmatrix.formats` submodules. Python 2 support was officially dropped with the 1.0 release.fixUpdate import paths (e.g., `from canmatrix.cli import convert`, `from canmatrix.formats import dbc`). Ensure your environment uses Python 3.8+ for current versions.
affects: <1.0
gotchaTo work with specific CAN database formats (e.g., ARXML, KCD, XLSX, YAML), you often need to install `canmatrix` with additional optional dependencies. A basic `pip install canmatrix` will not include these, leading to `ModuleNotFoundError` when trying to load or save those formats.fixInstall `canmatrix` with the necessary extras, e.g., `pip install 'canmatrix[arxml]'` for ARXML support or `pip install 'canmatrix[xls,xlsx]'` for Excel support. Refer to the documentation for a complete list of optional dependencies.
affects: All versions
gotchaOlder versions of `canmatrix` might have compatibility issues with Python 3.12 and newer due to an incompatible `future` dependency. An issue regarding this (`#742`) was resolved in May 2024.fixUpgrade to `canmatrix` version 1.0 or later (ideally 1.2 or the latest available) to ensure full compatibility with Python 3.12+ environments. If stuck on an older version, consider downgrading Python or manually patching.
affects: <1.0 (prior to fix in May 2024)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'lxml'
Canmatrix requires additional, optional dependencies for specific file formats (e.g., 'lxml' for ARXML, 'openpyxl' for XLSX). A basic `pip install canmatrix` does not include these, leading to a `ModuleNotFoundError` when attempting to load or save those formats.
fixInstall `canmatrix` with the necessary optional dependencies using bracket notation, e.g., `pip install 'canmatrix[arxml]'` for ARXML support or `pip install 'canmatrix[xls,xlsx]'` for Excel support.
ModuleNotFoundError: No module named 'canmatrix.formats.dbc'
Major internal refactoring and module reorganization in `canmatrix` versions leading up to 1.0 (specifically around 0.8 and 0.9) introduced breaking changes. Direct imports of modules like `canmatrix.convert` or `canmatrix.formats.<format>` from earlier versions are likely to fail as components were moved.
fixUpdate import paths to reflect the new structure. For example, use `from canmatrix.formats import dbc` for loading/dumping DBC files, and `from canmatrix.cli import convert` for command-line utilities.
TypeError: 'NoneType' object is not iterable
This error often occurs when `canmatrix` fails to parse an input CAN database file (e.g., DBC, ARXML, XLSX), causing a loading function to return `None` instead of a `CanMatrix` object. Subsequent operations attempting to iterate over the (non-existent) matrix then raise this `TypeError`. This can be due to a malformed file or missing format-specific dependencies.
fixEnsure the input CAN database file is valid and well-formed. Verify that all optional dependencies for the specific file format are installed (see `ModuleNotFoundError` entry). If the file is valid and dependencies are met, consider upgrading `canmatrix` to the latest version to benefit from parsing improvements.
DeprecationWarning: The SafeConfigParser class has been renamed to ConfigParser in Python 3.2. This alias will be removed in Python 3.12.
Older versions of `canmatrix` (prior to version 1.0/1.2) had compatibility issues with Python 3.12 and newer versions due to reliance on the deprecated `SafeConfigParser` class or the `future` compatibility library.
fixUpgrade `canmatrix` to version 1.0 or later (ideally 1.2 or the latest available) to ensure full compatibility with Python 3.12+ environments, as these versions have addressed the `future` dependency and other compatibility issues.
ModuleNotFoundError: No module named 'canmatrix'
The `canmatrix` library is not installed in the Python environment where the script is being executed.
fixInstall the library using pip: `pip install canmatrix`
Upgrade
Version history
1.2latest on PyPI · released Feb 17, 2025
Audit
Dependencies
attrsrequiredCore dependency for object serialization.
clickrequiredCore dependency for command-line interface tools.
lxmloptionalRequired for processing XML-based formats such as ARXML, KCD, Fibex, and ODX.
xlrdoptionalRequired for reading legacy .xls Excel files.
xlwt-futureoptionalRequired for writing legacy .xls Excel files.
XlsxWriteroptionalRequired for writing .xlsx Excel files.
PyYAMLoptionalRequired for processing YAML format.