How to Install MuJoCo and LeRobot: Matching Versions by OS, With or Without a GPU

When you start with robot simulation and imitation learning, the first thing that breaks is usually not the model but the install. MuJoCo and LeRobot require different Python versions, and PyTorch’s CUDA build, your graphics driver and the rendering backend all have to line up. One mismatch is enough to stop you at import. This guide installs both packages into one environment using only the official documentation and PyPI release metadata as of October 22, 2026. By the end you will know which combination fits your OS and GPU and how to confirm that the install actually works.

If you have not picked a simulator yet, read the MuJoCo vs Isaac Lab vs PyBullet vs Genesis comparison first.

Match the versions both packages require

The mujoco page on PyPI lists 3.16.0, uploaded on October 14, 2026, with Requires-Python set to 3.10 or newer. The lerobot page on PyPI lists 0.6.1, uploaded on August 3, 2026, which requires Python 3.12 or newer and declares torch>=2.7,<2.12 as a dependency. The lowest version that satisfies both is 3.12, so this guide uses Python 3.12 throughout.

The table combines each package’s release file list with the platform notes in the LeRobot installation guide. The MuJoCo wheel bundles the MuJoCo library itself, so, as the MuJoCo Python docs put it, pip install mujoco is all you need; there is no separate binary to download. The flip side is that 3.16.0 only ships arm64 wheels for macOS, so an Intel Mac would need a source build.

On Linux, match the CUDA driver to the torch build

If you plan to train on a GPU, check your driver version with nvidia-smi before installing anything. According to the LeRobot installation guide, the default torch wheel on PyPI for Linux is built against CUDA 13.0 and has a driver floor of 580.65. With an older driver, install torch first, from an explicit index, before installing lerobot.

macOS and Windows use the default PyPI wheel (MPS and the Windows CUDA build, respectively), so you can skip this step there.

Install order: from environment to check script

The steps below use conda via miniforge. That is the approach the LeRobot docs recommend, and getting ffmpeg from conda-forge works with every PyTorch version.

1. Create and activate a Python 3.12 environment.
2. On Linux with NVIDIA, install torch first from the index that matches your driver.
3. On platforms that support TorchCodec, install ffmpeg from conda-forge. Intel Macs and Linux ARM fall back to pyav, so you can skip it there.
4. Install LeRobot with the extras you need, then install MuJoCo.
5. Run a check script that tests all three packages and the accelerator in one go.

conda create -y -n physai python=3.12
conda activate physai

# (Linux + NVIDIA, only if your driver is below 580.65) install torch first
pip install --index-url https://download.pytorch.org/whl/cu128 torch torchvision

conda install ffmpeg -c conda-forge
pip install 'lerobot[training]' mujoco

Inside WSL, add conda install evdev -c conda-forge as the docs instruct. The base lerobot package is intentionally lightweight: recording and calibration need the core_scripts extra, training needs training, SmolVLA needs smolvla, and the Pi0 family needs pi.

Once the install finishes, save the following as check_env.py and run it.

from importlib.metadata import version

import mujoco
import torch

xml = """
<mujoco>
  <worldbody>
    <body pos="0 0 1">
      <freejoint/>
      <geom type="box" size=".05 .05 .05"/>
    </body>
  </worldbody>
</mujoco>
"""
m = mujoco.MjModel.from_xml_string(xml)
d = mujoco.MjData(m)
for _ in range(200):
    mujoco.mj_step(m, d)

print("mujoco", mujoco.__version__, "box z:", round(float(d.qpos[2]), 3))
print("lerobot", version("lerobot"))
print("torch", torch.__version__,
      "cuda:", torch.cuda.is_available(),
      "mps:", torch.backends.mps.is_available())

If the box height z comes out below its starting value of 1, gravity was applied and the physics steps ran. Then check that whichever of cuda or mps applies to your machine reads True.

Pick a rendering backend for servers without a display

MuJoCo’s OpenGL rendering runs on one of three backends. The dm_control README says they are tried in the order GLFW, EGL, OSMesa, and that you can pin one with the MUJOCO_GL environment variable.

On multi-GPU machines, MUJOCO_EGL_DEVICE_ID selects the GPU used for rendering. To confirm the backend is picked up, create a mujoco.GLContext, which the MuJoCo Python docs describe for offscreen rendering.

export MUJOCO_GL=egl
python -c "import mujoco; ctx = mujoco.GLContext(640, 480); ctx.make_current(); print('GL context OK')"

Local macOS has a different catch when you use the interactive viewer. Per the docs, mujoco.viewer.launch_passive must run under the mjpython launcher on macOS, and mjpython is installed with the mujoco package. Run mjpython my_script.py instead of python my_script.py.

Options and limits when you have no GPU

You can install everything and run simulations without a GPU. MuJoCo physics runs on the CPU, and the check script above finishes without one. Policy training is where you hit the limit.

The Colab FAQ says notebooks on the free tier can run for at most 12 hours, depending on availability and usage patterns, and that usage limits fluctuate and are not published. When training on Colab, save checkpoints to the Hugging Face Hub or Drive often so you can resume after a disconnect. LeRobot links Colab training notebooks for ACT and SmolVLA from their respective docs pages.

How much GPU memory training needs varies a lot by model. The SmolVLA case is worked through in How Much GPU Memory Does SmolVLA Fine-Tuning Need?

Pin the environment so you can rebuild it

Once an install works, writing the versions down is the cheapest way to avoid the next breakage. The environment.yml below pins the reference versions used in this guide.

name: physai
channels:
  - conda-forge
dependencies:
  - python=3.12
  - ffmpeg
  - pip
  - pip:
      - mujoco==3.16.0
      - lerobot[training]==0.6.1

If you installed torch from a specific index on Linux, document that step in your README so it runs before conda env create -f environment.yml. To capture everything that actually got installed, run pip freeze > requirements.lock.txt; a teammate can then reproduce the exact same combination.

Where to look first when the install fails

With the install done, you can move straight to collecting SO-101 data and training ACT with LeRobot to validate your data pipeline. Which policy to start with, given how much data you have, is covered in Is 50 Demos Enough to Fine-Tune a VLA?.