Skip to content

installation_guide.md

Latest commit

 

History

History
178 lines (128 loc) · 5.65 KB

installation_guide.md

File metadata and controls

178 lines (128 loc) · 5.65 KB

mjlab Installation Guide

System Requirements

  • Python: 3.10 or higher
  • Operating System:
    • Linux (recommended)
    • macOS (limited support – see note below)
    • Windows (compatible - see note below)
  • GPU: NVIDIA GPU strongly recommended
    • CUDA Compatibility: Not all CUDA versions are supported by MuJoCo Warp

⚠️ Important Note on macOS: mjlab is designed for large-scale training in GPU-accelerated simulations. Since macOS does not support GPU acceleration, it is not recommended for training. Even policy evaluation runs significantly slower on macOS. We are working on improving this with a C-based MuJoCo backend for evaluation — stay tuned for updates.

Note on Windows: Since warp/mujoco-warp are supported on Windows, Windows compatibility is available with mjlab. Core functionality (e.g. the demo and train scripts) has been tested, but support for Windows should be considered experimental. Windows users may also consider WSL as an option.

⚠️ Beta Status

mjlab is currently in beta. Expect frequent breaking changes in the coming weeks. There is no stable release yet.

  • The first beta snapshot is available on PyPI.
  • Recommended: install from source (or Git) to stay up-to-date with fixes and improvements.

Prerequisites

Install uv

If you haven't already installed uv, run:

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

Installation Methods

Method 1: From Source (Recommended)

Use this method if you want the latest beta updates.

Option A: Local Editable Install

  1. Clone the repository:
git clone https://github.com/mujocolab/mjlab.git
cd mjlab
  1. Add as an editable dependency to your project:
uv add --editable /path/to/cloned/mjlab

Option B: Direct Git Install

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@fb9bf88399796f161a4a2b129d846484da8a4ad0"

Note: mujoco-warp must be installed from Git since it's not available on PyPI.

Method 2: From PyPI (Beta Snapshot)

You can install the latest beta snapshot from PyPI, but note:

  • It is not stable
  • You still need to install mujoco-warp from Git
uv add mjlab "mujoco-warp @ git+https://github.com/google-deepmind/mujoco_warp@486642c3fa262a989b482e0e506716d5793d61a9"

Method 3: Using pip (venv, conda, virtualenv, etc.)

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

  1. Create and activate your virtual environment:

    Using venv (built-in):

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

    Using conda:

    conda create -n mjlab python=3.13
conda activate mjlab

  2. Install mjlab and dependencies via pip:

    From Source (Recommended):

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

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

    From PyPI:

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

Method 4: Docker

  • Install Docker
  • Install an appropriate NVIDIA driver for your system and the NVIDIA Container Toolkit
  • make docker-build
  • Use the included helper script to run an mjlab docker container with many useful arguments included: ./scripts/run_docker.sh
    • 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

Verification

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

# If working inside the mjlab directory with uv.
uv run demo

# If mjlab is installed as a dependency in your project with uv.
uv run python -m mjlab.scripts.demo

# If installed via pip (conda, venv, etc.), use the CLI command directly.
demo

# Or use the module syntax (works anywhere mjlab is installed).
python -m mjlab.scripts.demo

Troubleshooting

If you run into problems:

  1. Check the FAQ: faq.md may have answers to common issues.
  2. CUDA Issues: Verify your CUDA version is supported by MuJoCo Warp (see compatibility list).
  3. macOS Slowness: Training is not supported; evaluation may still be slow (see macOS note above).
  4. Still stuck? Open an issue on GitHub Issues.