Installation Guide

Installation Guide#

mjlab is in active beta and tightly coupled to MuJoCo Warp. 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.

Install uv#

If you do not have uv installed, run:

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

Add mjlab dependency#

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@9fc294d86955a303619a254cefae809a41adb274"

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@9fc294d86955a303619a254cefae809a41adb274"

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

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@9fc294d86955a303619a254cefae809a41adb274
pip install mjlab

From Source:

pip install git+https://github.com/google-deepmind/mujoco_warp@9fc294d86955a303619a254cefae809a41adb274
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