Install & Compatibility
Where this runs
tested against v1.5.0 · 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.960 runs
installs and imports cleanly · install 0.0s · import 0.244s · 68MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 3.1s · import 0.234s · 72MB
69MB installed
● package 69MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RDLCompiler
✓ from systemrdl import RDLCompiler
While 'peakrdl' is primarily a CLI, its Python API for extensions (like `peakrdl-python`, `peakrdl-cheader`) often requires `systemrdl.RDLCompiler` to parse RDL files programmatically. There isn't a single 'main' import from the `peakrdl` package itself for typical user-facing programmatic tasks beyond plugin development.
PythonExporter
✓ from peakrdl_python.exporter import PythonExporter
For generating Python Register Access Layers (RALs) via Python API. This requires the 'peakrdl-python' package.
CHeaderExporter
✓ from peakrdl_cheader.exporter import CHeaderExporter
For generating C Header files via Python API. This requires the 'peakrdl-cheader' package.
This quickstart demonstrates how to use the `peakrdl` command-line tool to generate a C header file and HTML documentation from a simple SystemRDL description. First, create a file named `example.rdl` with the provided content, then run the `peakrdl` commands in your terminal.
# example.rdl
addrmap my_device {
reg {
field { sw = rw; hw = r; } control_field[7:0] = 0;
field { sw = r; hw = w; } status_field[15:8] = 0;
} my_register;
regfile my_block [2] {
reg { field { sw = rw; } data[31:0] = 0; } data_reg;
};
};
# Terminal commands
# Generate a C header file
peakrdl c-header example.rdl -o example.h
# Generate HTML documentation
peakrdl html example.rdl -o html_docs/
peakrdl --version
Debug
Known issues
breakingPeakRDL v1.3.0 dropped support for Python 3.6. Ensure your environment uses Python 3.7 or newer to avoid compatibility issues.fixUpgrade your Python environment to version 3.7 or higher.
affects: >=1.3.0
breakingThe `peakrdl-python` package (version 0.9.0) introduced a breaking API change for handling blocks (registers in arrays, memory entries) to address limitations in implementing the full SystemRDL specification.fixReview the `peakrdl-python` documentation for versions 0.9.0 and above, specifically regarding block access methods, and update your code accordingly. The `legacy_block_access` option in `PythonExporter` might be relevant for older code.
affects: >=0.9.0 of peakrdl-python
gotchaPeakRDL v1.4.0 changed its licensing from MIT to GNU LGPLv3 for the CLI and all core extensions. While LGPLv3 is permissive, review its terms if you are redistributing PeakRDL or its generated code in proprietary projects.fixConsult the GNU LGPLv3 license to understand the implications for your project, especially regarding linking and distribution of derived works.
affects: >=1.4.0
gotchaFrom `peakrdl-python` v3.0.0, a new custom enumeration type is used by default in generated Python Register Access Layers (RALs) to expose SystemRDL `name` and `desc` properties. Older code relying on `IntEnum` behavior might need adjustment.fixIf your generated code relies on the old `IntEnum` type, set the `legacy_enum_type=True` parameter in the `PythonExporter` when generating your RAL.
affects: >=3.0.0 of peakrdl-python
gotchaSystemRDL allows identifiers to be repeated in different lexical scopes. If an exporter flattens hierarchy or uses common namespaces, this can lead to name collisions in the generated output. Similarly, different enumerations can have the same `state_e` name.fixTool developers should use `Node.get_path()` or `get_scope_path()` to ensure unique identifiers in generated code, or implement strategies to disambiguate names.
affects: *
Errors
Common errors & fixes
peakrdl: command not found
The `peakrdl` executable is not in your system's PATH, or the package was not installed correctly.
fixEnsure `peakrdl` is installed (`pip install peakrdl`) and that your Python environment's script directory is included in your system's PATH. You can often run it directly via `python -m peakrdl <command>`.
Command '['python', '-m', 'peakrdl_something']' returned non-zero exit status 1.
A `peakrdl` subcommand (which are often separate packages like `peakrdl-python`, `peakrdl-cheader`) failed. This typically means the specific extension is not installed or has encountered an internal error.
fixVerify that the specific `peakrdl-*` extension (e.g., `peakrdl-python`) is installed (`pip install peakrdl-python`). If it is, check the error output from the failing subcommand for more details (e.g., RDL compilation errors, configuration issues).
Error: peakrdl.plugins.PluginError: Plugin 'my_custom_plugin' could not be loaded
PeakRDL failed to discover or load a custom plugin. This could be due to incorrect entry point configuration in `setup.py`, a typo in the plugin's module path, or issues within the plugin's code.
fixEnsure your custom plugin is correctly defined with an `importer` or `exporter` entry point in your `pyproject.toml` or `setup.py`, and that the `__peakrdl__.py` file at your package root is correct. Alternatively, verify its path if using `peakrdl.toml` for configuration.
from peakrdl_python import compiler_with_udp_registers
ImportError: cannot import name 'compiler_with_udp_registers' from 'peakrdl_python'
This import path or symbol might be incorrect, deprecated, or specific to an older/newer version of `peakrdl-python`.
fixRefer to the `peakrdl-python` documentation for the correct import paths. The `compiler_with_udp_registers` function is part of the `peakrdl_python` package, so ensure it is installed and that the documentation for your version shows this import as valid. Many examples now use `systemrdl.RDLCompiler` directly.
Upgrade
Version history
1.5.0latest on PyPI · released Oct 3, 2025
Audit
Dependencies
systemrdl-compilerrequiredInternal dependency for parsing SystemRDL files, often directly imported when using the Python API of PeakRDL extensions.