Installation¶

Linux/MacOS¶

Prerequisites¶

git
Python 3.11 or higher
acados dependencies

We recommend the uv package manager. Install it with

curl -LsSf https://astral.sh/uv/install.sh | sh

(see the uv installation guide for other options). If you prefer, the classic pip + venv workflow is also fully supported — the alternative commands are shown alongside each step below.

Clone the repository and recursively update submodules:

git clone https://github.com/leap-c/leap-c.git
cd leap-c
git submodule update --init --recursive

Python¶

Create a virtual environment and activate it. Assuming a required Python version of 3.11 or newer, you can use the following commands.

Recommended (uv), which also fetches a matching Python if it is not installed:

uv venv --python 3.11
source .venv/bin/activate

Alternatively (pip/venv):

python3 -m venv .venv
source .venv/bin/activate

The following steps assume that the virtual environment is activated.

acados¶

Then change into the acados directory

cd external/acados

and build it as described in the acados documentation. When running the cmake command, include the options -DACADOS_WITH_OPENMP=ON -DACADOS_NUM_THREADS=1. Afterwards, install the python interface of acados. When the acados docs use pip install, you can substitute uv pip install as a drop-in replacement inside the activated environment.

Backend¶

leap-c does not auto-install a computational backend. Select one via its optional extra:

Extra	Framework	Required for
`torch`	PyTorch	`AcadosDiffMpcTorch`
`jax`	JAX	(planned)

uv:

uv sync --extra torch                                           # GPU (default)
uv sync --extra torch --index-url https://download.pytorch.org/whl/cpu  # CPU-only

pip (requires acados_template installed first — see acados above):

pip install -e ".[torch]"                                       # GPU (default)
pip install -e ".[torch]" --extra-index-url https://download.pytorch.org/whl/cpu  # CPU-only

If no backend is installed and you try to import a backend-specific module, leap-c raises a clear error telling you which backends are supported.

Install leap-c¶

uv sync                      # minimal install (no backend)
uv sync --extra dev          # minimal + torch, docs, test, pre-commit
pip install -e ".[dev]"      # pip equivalent

See the pyproject.toml for more information on package configurations.

Troubleshooting¶

In the troubleshooting tab, we highlight how to fix common problems arising while using leap-c with VS Code.

Docker (optional fallback)¶

Docker is an optional fallback for users who want a reproducible environment with pre-built acados without compiling it locally. For regular development, we recommend the native installation above.

Pre-built images are published to GitHub Container Registry. To run the interactive marimo notebook server (no build required):

docker run -it --rm -p 7860:7860 ghcr.io/leap-c/leap-c:notebook

Open http://localhost:7860 in your browser. For persisting notebook edits, using the CPU shell image, and the full local-build/GPU/Dev Container instructions, see Running Notebooks.

For advanced Docker configuration, Dockerfile stages, CI, and troubleshooting, see docker/README.md.

Windows¶

We recommend to use WSL (Windows Subsystem for Linux) and then following the guide above. You can then conveniently program on your WSL, e.g., by using VS Code on Windows together with the “Remote Development” extension pack.

Note the installation instructions for acados regarding WSL. Also note the troubleshooting section for plt.show() in WSL below.

Testing¶

To run the tests, use:

pytest tests -vv -s

Linting and Formatting¶

Only relevant if you want to contribute to the repository. For keeping our code style and our diffs consistent we use the Ruff linter and formatter.

To make this as easy as possible we also provide a pre-commit config for running the linter and formatter automatically at every commit. For enabling pre-commit follow these steps:

Install pre-commit (already done if you installed the additional “[dev]” dependencies of leap-c). Recommended (uv):

uv pip install pre-commit

Alternatively (pip):

pip install pre-commit

In the leap-c root directory run

pre-commit install

Done! Now every commit will automatically be linted and formatted.