Install MuJoCo 3.8.0: The Pip-First Setup Guide

End state you’re aiming for: a terminal where python -m mujoco.viewer pops open an interactive 3D window with a model you can drag around with the mouse – and a Python session that can step physics deterministically for reinforcement learning or robotics work. That’s it. If you’ve been chasing the older ~/.mujoco/mujoco210 tar-extract-and-edit-bashrc tutorials, throw them out. The modern path is one pip command.

This guide covers physics simulation AI setup with MuJoCo 3.8.0, the latest stable release published on 24 April 2026 by Google DeepMind. We skip the legacy mujoco-py binary dance – which around 80% of tutorials still teach – and focus on what actually works as of mid-2026.

Why install MuJoCo at all

MuJoCo is the physics engine behind most serious robotics RL research – humanoid locomotion, dexterous manipulation, sim-to-real transfer. DeepMind acquired it in October 2021 and open-sourced it in 2022, which is when the install story became manageable. Before that: a license key, a binary tarball, and a lot of environment variables. Now you don’t need any of that.

What actually makes it the default choice for RL research isn’t magic – it’s that MuJoCo has been the benchmark platform long enough that most frameworks (Gymnasium, dm_control, mujoco_playground) are built around it. Switching means rewriting your environment code. Most researchers don’t.

System requirements

The one hard requirement that trips people up: MuJoCo requires a processor with AVX instructions (per the MuJoCo programming docs). Anything from roughly 2011 onward has it, but cheap cloud VMs and some ARM boards don’t. Check with cat /proc/cpuinfo | grep avx before you bother.

No Windows ARM support, no 32-bit anything – those are simply not in the precompiled binary set.

Install MuJoCo (the one command you actually need)

Create a virtual environment first. Conda, venv, uv – pick your poison. Then:

python -m venv mj-env
source mj-env/bin/activate # Windows: mj-envScriptsactivate
pip install mujoco

Done. A copy of the MuJoCo library ships inside the package and needs no separate download. No ~/.mujoco folder, no LD_LIBRARY_PATH edits, no license key. If a tutorial tells you to wget a tarball, it’s from before 2022.

The PyPI package version tracks the C library directly – mujoco==3.8.0 gives you MuJoCo 3.8.0’s C library bundled in. The Python bindings are built in C++ with pybind11, so they’re a thin wrapper over the C API, not a reimplementation.

Alternative: building from source

You only need this if you’re modifying the engine itself or targeting an unusual platform. You’ll need CMake and a C++17 compiler. Then:

git clone https://github.com/google-deepmind/mujoco.git
cd mujoco
cmake -B build
cmake --build build

MuJoCo’s build system pulls dependencies automatically via CMake’s FetchContent – expect a few hundred MB on first run. No manual dependency hunting.

Verify it works

Import check first:

python -c "import mujoco; print(mujoco.__version__)"

You should see 3.8.0. Then the viewer – no arguments opens an empty 3D window where you can drag-and-drop an MJCF file:

python -m mujoco.viewer

Window opens, you can rotate the scene. You’re done. If it doesn’t open, jump to the errors section.

The macOS trap nobody tells you about

Passive viewer. That’s where it breaks. The blocking call (python -m mujoco.viewer) works fine – but every RL training loop uses viewer.launch_passive, and on macOS that silently does nothing when you run it with regular python.

The cause: macOS requires the main thread to handle rendering. Regular Python can’t guarantee that. MuJoCo ships a workaround – the mjpython launcher – which is installed automatically as part of the mujoco package. According to the official Python docs, launch_passive on macOS must be executed via mjpython, which handles the threading constraint. Use it as a drop-in replacement:

mjpython train.py # instead of: python train.py

Easy fix once you know. Frustrating for hours if you don’t.

Pro tip: Shipping training code that others will run on Mac? Detect the platform and print a one-line warning telling them to use mjpython. Save them the debugging session you just had.

Headless servers: pick EGL

EGL. That’s the answer. The rest of this section explains why, but if you’re on a headless box and need to move fast, set these and skip ahead:

export MUJOCO_GL=egl
export PYOPENGL_PLATFORM=egl

The docs (and the torchrl knowledge base) list three backends without telling you which to use. Turns out the choice is easy: glfw won’t run without a display, osmesa won’t use the GPU. That leaves EGL for any headless environment where you want GPU rendering. On Ubuntu you’ll also want the rendering stack installed – community reports suggest sudo apt-get install libglfw3 libglew2.0 libgl1-mesa-glx libosmesa6, though exact package names may vary by distro version.

There’s an uncomfortable truth about headless RL that doesn’t get said enough: you can set all the right env vars and still get blank renders if your CUDA driver and EGL aren’t speaking to each other. When that happens, nvidia-smi shows the GPU but python -c "import OpenGL" throws. That’s a driver issue, not a MuJoCo issue – but MuJoCo will get the blame.

Common errors and what they actually mean

• Illegal instruction (core dumped) on import: Your CPU lacks AVX. No software fix. Use a different machine.
• Viewer opens then closes immediately on macOS: You called launch_passive from regular python. Switch to mjpython.
• GLEW initialization error: Unknown error: A mujoco-py artifact. If you’re hitting this, you’re following a 2021-era tutorial. Uninstall mujoco-py and use the modern bindings.
• Gymnasium can’t find Ant-v4, HalfCheetah-v4, etc.: As of Gymnasium v1.2, the legacy v2/v3 MuJoCo environments have moved to the gymnasium-robotics package. Install it separately: pip install gymnasium-robotics.
• RL training is non-reproducible on RTX 30/40 GPUs: JAX defaults to TF32 on Ampere GPUs. Per the mujoco_playground README, run export JAX_DEFAULT_MATMUL_PRECISION=highest before experiments. Without it, matrix multiply precision varies run-to-run.

Upgrading and the version-drift trap

Upgrading is trivial: pip install -U mujoco. Within a project, freeze the version. MuJoCo aims to ship in the first week of every month (as of 2026), using modified Semantic Versioning since 3.5.0. Monthly releases means drift accumulates fast.

The downstream packages don’t always keep up. MuJoCo Playground had to patch a breaking change between 3.3.2 and 3.3.3 – light_directional was renamed to light_type, which broke existing environment configs. A point release silently broke a major DeepMind training framework. If a demo crashes after a MuJoCo update, check the downstream package’s changelog before assuming your code is wrong.

How much should you worry about this? Honestly, for most projects – pin your versions in requirements.txt and forget about it. The versioning instability matters mainly if you’re tracking latest-main or building a library that others depend on. For a personal RL experiment, freezing once and re-evaluating every few months is enough.

Uninstall

pip uninstall mujoco. No system-wide residue, no ~/.mujoco left behind (unless you made one for legacy mujoco-py), no registry keys. The bundled library lives in site-packages and goes with the package.

Installed dm_control or gymnasium-robotics alongside? Uninstall those separately – they don’t chain.

FAQ

Do I still need a license key?

No. MuJoCo was open-sourced in 2022. If a tutorial mentions mjkey.txt, skip that step entirely.

Should I use mujoco or mujoco-py?

Use mujoco. The mujoco-py package was the legacy OpenAI binding – it’s no longer maintained. The only scenario where you’d touch it is maintaining old research code, like the v2/v3 Gymnasium MuJoCo environments that have since migrated to gymnasium-robotics. Even then, the migration docs recommend porting rather than keeping mujoco-py around. For any new project: pip install mujoco, done.

Can I run MuJoCo on a GPU for faster RL training?

Yes – but the setup is deeper than a single pip command. Two paths: MJX (MuJoCo’s JAX port) and MuJoCo Warp, which is now officially released and is the default backend for mujoco_playground environments. Both require CUDA 12 and a working JAX GPU install, and JAX’s dependency chain has its own failure modes. Start from the official MuJoCo docs rather than random tutorials – the GPU stack changes fast enough that anything older than a few months may describe a different install flow. The payoff, once it works: thousands of parallel environments where you used to run one.

Next: clone mujoco_playground, run the CartpoleBalance demo on Warp, and watch what parallel RL rollouts actually feel like when the simulator isn’t the bottleneck.