Installation Guide

Installation Guide#

This guide presents different installation paths so you can choose the one that best fits your use case.

Note

System Requirements

  • Training: Linux + NVIDIA GPU (CUDA 12.4+ recommended)

  • Evaluation: Linux, macOS, or Windows (WSL)

  • Python: 3.10 or higher

See FAQ & Troubleshooting for more details on what is exactly supported.

How to choose an installation method?#

Select the card that best matches how you plan to use mjlab.

Method 1 - Use mjlab as a dependency (uv)

You are using mjlab as a dependency in your own project managed by uv. (Recommended for most users)

Method 1 - Use mjlab as a dependency (uv)
Method 2 - Develop / contribute (uv)

You are trying mjlab or contributing to mjlab itself directly from inside the mjlab repository, with uv managing the environment.

Method 2 - Develop / contribute (uv)
Method 3 - Classic pip / venv / conda

You are using classic tools (pip / venv / conda) and do not use uv.

Method 3 - Classic pip / venv / conda
Method 4 - Docker / clusters

You are running in containers or on clusters and prefer a Docker-based setup.

Method 4 - Docker / clusters

Method 1 - Use mjlab as a dependency (uv)#

This is our recommended way to use mjlab. You have your own project and want to use mjlab as a dependency using uv.

1. Install uv#

If you do not have uv installed, run:

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

2. Initialize your project#

Initialize a managed Python project:

# Create a new package-based project
uv init --package my_mjlab_project
cd my_mjlab_project

3. Add mjlab dependencies#

There are different options to add mjlab as a dependency. We recommend using the latest stable version from PyPI. If you need the latest features, use the direct GitHub installation. Finally, if you need to use a feature you have developed locally, use the local editable install. These options are interchangeable: you can switch at any time.

Once in your project, install the latest snapshot from PyPI:

uv add mjlab

Once in your project, install directly from GitHub without cloning:

uv add "mjlab @ git+https://github.com/mujocolab/mjlab"

Clone the repository:

git clone https://github.com/mujocolab/mjlab.git

Once in your project, add it as an editable dependency:

uv add --editable /path/to/cloned/mjlab

Tip

For a complete example of how to structure a project that integrates a custom robot with an existing mjlab task, check out the ANYmal C Velocity Tracking repository.

Verification#

After installation, verify that mjlab is working by running the demo:

uv run demo

Method 2 - Develop / contribute (uv)#

This method is for developing mjlab itself or contributing to the project.

git clone https://github.com/mujocolab/mjlab.git && cd mjlab
uv sync

Verification#

After installation, verify that mjlab is working by running the demo:

uv run demo

Method 3 - Classic pip / venv / conda#

Activate your virtual environment (venv, conda, etc.), then install:

pip install mjlab

Verification#

After installation, verify that mjlab is working by running the demo:

demo

Method 4 - Docker / clusters#

Prerequisites:

  • Install Docker: Docker installation guide.

  • Install an appropriate NVIDIA driver for your system and the NVIDIA Container Toolkit.

    • Be sure to register the container runtime with Docker and restart, as described in the Docker configuration section of the NVIDIA install guide.

Pull and run the latest image from the GitHub Container Registry:

docker run --rm --runtime=nvidia --gpus all \
  ghcr.io/mujocolab/mjlab uv run demo

The image is rebuilt on every push to main.

Build from source and run:

./scripts/run_docker.sh uv run demo

Having some troubles?#

  1. Check the FAQ

    Consult the mjlab FAQ & Troubleshooting for answers to common installation and runtime issues

  2. Still stuck?

    Open an issue on GitHub: mujocolab/mjlab#issues

Contents