Install & Compatibility
Where this runs
tested against v3.12.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 7.1s
py 3.12
✕ build_error
✓ 6.7s
py 3.13
✕ build_error
✓ 6.7s
py 3.9
✕ build_error
✕ build_error
178MB installed
● package 178MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mujoco
✓ import mujoco
✗ import mujoco_py
The `mujoco_py` library is deprecated and unmaintained; use the official `mujoco` package.
MjModel
✓ import mujoco
model = mujoco.MjModel.from_xml_string(...)
MjData
✓ import mujoco
data = mujoco.MjData(model)
mj_step
✓ import mujoco
mujoco.mj_step(model, data)
This example loads a basic XML model of a sphere dropping onto a plane and simulates it for 100 steps, printing its initial and final vertical position. It demonstrates the core `MjModel`, `MjData`, and `mj_step` functionalities.
import mujoco
import numpy as np
# Create a simple XML model string for a sphere on a plane
xml_string = """
<mujoco model="sphere_drop">
<worldbody>
<geom name="floor" type="plane" size="0 0 0.1" material="grid"/>
<body name="sphere" pos="0 0 1">
<geom name="ball" type="sphere" size="0.1" material="sphere_mat"/>
</body>
</worldbody>
<asset>
<texture type="2d" name="grid" builtin="checker" width="512" height="512" rgb1="0.1 0.2 0.3" rgb2="0.2 0.3 0.4" mark="edge" markrgb="0.8 0.8 0.8"/>
<material name="grid" texture="grid" texrepeat="1 1" texuniform="true"/>
<material name="sphere_mat" rgba="0.7 0 0 1"/>
</asset>
</mujoco>
"""
# Load the model and create data
model = mujoco.MjModel.from_xml_string(xml_string)
data = mujoco.MjData(model)
# Simulate for 100 steps
print(f"Initial sphere position: {data.qpos[2]:.3f}") # Assuming Z is the 3rd element of qpos
for i in range(100):
mujoco.mj_step(model, data)
print(f"Final sphere position: {data.qpos[2]:.3f}")
mjpython --version
Debug
Known issues
breakingThe official `mujoco` Python package (maintained by Google DeepMind) replaced the community-developed `mujoco_py`. `mujoco_py` is deprecated, unmaintained, and should not be used in new projects.fixUninstall `mujoco_py` and `pip install mujoco`. Rewrite code to use the new `mujoco` API. Consult official documentation for API changes.
affects: All versions of `mujoco` (from 2.0.0 onwards) when migrating from `mujoco_py`.
breakingMuJoCo 3.0.0 introduced a substantial redesign of the Python Bindings API. Code written for pre-3.0 versions will likely break, especially regarding `mjx` (JAX integration) and `mjcf` (model construction) utilities.fixCarefully review the official changelog (e.g., for `3.0.0`) and update API calls according to the new design. Many module structures and function signatures have changed.
affects: Versions `mujoco < 3.0.0` when upgrading to `mujoco >= 3.0.0`.
gotchaThe `mujoco` Python package itself does not include a visualizer. To render simulations, you typically need to install an additional library like `mujoco_viewer` or integrate with `dm_control`.fixInstall `mujoco_viewer` (`pip install mujoco_viewer`) and use its API for basic visualization, or integrate with a full environment framework like `dm_control` for more advanced rendering and control.
affects: All versions.
gotchaThe `mujoco` Python package officially requires Python 3.10 or newer. Installing with older Python versions may lead to errors or unexpected behavior due to incompatibility with the pre-compiled binaries.fixEnsure your Python environment is version 3.10 or newer. Use `python --version` to check and upgrade if necessary.
affects: All versions `>= 3.0.0`.
Errors
Common errors & fixes
ImportError: No module named 'mujoco'
The 'mujoco' package is not installed or not found in the Python environment.
fixInstall the 'mujoco' package using pip: 'pip install mujoco'.
ImportError: No module named 'mujoco_py.mjlib'
The 'mujoco_py' package is not installed or improperly configured.
fixInstall the 'mujoco_py' package using pip: 'pip install mujoco-py'.
dyld: Library not loaded: ... Reason: image not found
The dynamic linker cannot find essential system files required by MuJoCo or its dependencies.
fixEnsure all necessary libraries are installed and properly linked. On macOS, updating or reinstalling MuJoCo and its dependencies may resolve the issue.
libGL error: failed to load driver: radeonsi
The system lacks the necessary OpenGL drivers or they are misconfigured.
fixInstall or update the appropriate OpenGL drivers for your system. On Linux, this may involve installing 'libgl1-mesa-dri' and related packages.
AttributeError: module 'mujoco' has no attribute 'MjModel'
The 'mujoco' package is outdated or incompatible with the current code.
fixUpdate the 'mujoco' package to the latest version using pip: 'pip install --upgrade mujoco'.
Upgrade
Version history
3.12.0latest on PyPI · released Aug 20, 2026
Audit
Dependencies
No dependency data recorded yet.