Installation guide

You will need Python 3.13, uv, git, and the local build tools required by the Python extension. The package builds and embeds its bundled simulation engine, so you do not need to install a separate runtime library before using Cimba Python.

Linux

On Linux, clone the repository and let uv create the project environment:

git clone <repo-url> cimba_python
cd cimba_python
uv sync

On Ubuntu or WSL, install the usual native build packages first:

sudo apt install build-essential nasm libhdf5-dev

Use uv run for commands that should execute inside the project environment.

Windows

On Windows, install Python 3.13, uv, git, NASM, and a supported compiler toolchain. Then run the same project commands from a developer shell:

git clone <repo-url> cimba_python
cd cimba_python
uv sync

If Windows Security blocks build tools from writing into the project directory, allow the compiler, assembler, and Python build tools. If imports fail because another application provides incompatible runtime DLLs earlier on PATH, adjust PATH so the active compiler environment comes first.

macOS

Apple Silicon Macs are supported with native arm64 wheels, so the normal installation does not require Xcode or a separate Cimba library:

python -m pip install cimba

For a source checkout, install Xcode Command Line Tools, clone the repository, and run uv sync. Intel Macs are not currently supported because Numba does not publish the required llvmlite wheels for that architecture.

Verifying your installation

Verify that Python can import the package:

uv run python -c "import cimba; print(cimba.native_version())"

If all goes well, this prints a version such as:

3.0.0-beta

Run the test suite with:

uv run pytest

The tests build and execute small cimba.sim models covering imports, logging, declarations, queues, resources, pools, stores, priority queues, conditions, random draws, process signals, timers, dynamic processes, events, and parallel experiments.