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

  • Operating System: Linux recommended

  • Python: 3.10 or higher

  • GPU: NVIDIA GPU

  • CUDA version: CUDA 12.4+ Recommended

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 "mujoco-warp @ git+https://github.com/google-deepmind/mujoco_warp@7c20a44bfed722e6415235792a1b247ea6b6a6d3"

Note

mujoco-warp must be installed from GitHub since it’s not available on PyPI.

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

uv add "mjlab @ git+https://github.com/mujocolab/mjlab" "mujoco-warp @ git+https://github.com/google-deepmind/mujoco_warp@7f89cacecbf0baff92a631671d4a7a45c2b07e20"

Note

mujoco-warp must be installed from GitHub since it’s not available on PyPI.

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#

While mjlab is designed to work with uv, you can also use it with any pip-based virtual environment (venv, conda, virtualenv, etc.).

Create and activate your virtual environment#

Using venv (standard library):

python -m venv mjlab-env
source mjlab-env/bin/activate

Using conda:

conda create -n mjlab python=3.13
conda activate mjlab

Install mjlab and dependencies via pip#

From PyPI:

pip install git+https://github.com/google-deepmind/mujoco_warp@7c20a44bfed722e6415235792a1b247ea6b6a6d3
pip install mjlab

From Source:

pip install git+https://github.com/google-deepmind/mujoco_warp@7f89cacecbf0baff92a631671d4a7a45c2b07e20
git clone https://github.com/mujocolab/mjlab.git
cd mjlab
pip install -e .

Note

You must install mujoco-warp from GitHub before running pip install -e . since it’s not available on PyPI and pip cannot resolve the GitHub dependency specified in pyproject.toml (which uses uv-specific syntax).

Verification#

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

demo

Method 4 - Docker / clusters#

This method is recommended if you prefer running mjlab in containers (for example on servers or 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.

Build the Docker image#

From the root of the repository:

make docker-build

Run mjlab in Docker#

Use the included helper script to run an mjlab Docker container with useful arguments preconfigured:

./scripts/run_docker.sh

Examples:

  • Demo with viewer:

    ./scripts/run_docker.sh uv run demo

  • Training example:

    ./scripts/run_docker.sh uv run train Mjlab-Velocity-Flat-Unitree-G1 --env.scene.num-envs 4096

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