MuJoCo Menagerie: Curated Robot Models for MuJoCo, and How to Load One

The bad-model problem Menagerie exists to fix

MuJoCo exposes many modeling options, and the README is blunt about the consequence: it is easy to create "bad" models which do not behave as expected. A simulator's output is bounded by the model fed into it, so a malformed kinematic tree, a wrong inertia, or a collision geometry that self-intersects will produce simulation results that look plausible and are wrong. Menagerie's stated goal is to give the community a curated library of well-designed models that work well right out of the gate.

The audience is therefore narrow and practical: robotics researchers and engineers who need a working MuJoCo model of a specific commercial or research robot (Unitree, Franka Emika, Boston Dynamics Spot, Robotiq grippers, and so on) rather than a model they authored themselves. The repository directory listing shows the breadth: franka_emika_panda, franka_fr3, unitree_go2, boston_dynamics_spot, robotiq_2f85, leap_hand, and dozens more, each in its own top-level directory. If you are building a control stack, an RL environment, or a manipulation benchmark and you would otherwise spend days writing MJCF by hand, that is the case Menagerie is aimed at.

How a Menagerie model is laid out on disk

Every model directory follows the same pattern, which the README illustrates with unitree_go2. The assets subdirectory holds 3D meshes in .stl or .obj used for visual and collision purposes. The model file <model>.xml contains the MJCF definition. scene.xml includes <model>.xml along with a plane, a light source, and potentially other objects. A PNG preview of the scene sits next to them, and a LICENSE file describes the copyright and licensing terms of that specific model.

The split between <model>.xml and scene.xml is a deliberate design choice, and it is the detail most worth internalizing. The README states that <model>.xml solely describes the model, with no other entity defined in the kinematic tree, and that additional body definitions are left to the scene.xml file, as in the Shadow Hand scene_right.xml. That means if you want a robot standing on a floor with a table and a cube, you do not edit the model file; you write your own scene that includes it. This keeps upstream model files clean and diffable, and it is why scene.xml exists as a separate artifact at all.

Some models also ship a <model>_mjx.xml and a scene_mjx.xml. The README notes that the MJX variant is an MJX-compatible version of the model and that not all models have one. If you are targeting GPU-accelerated MJX, check for the suffix before assuming it is present.

Installing mujoco-menagerie and loading your first model

The README presents the Python package as the easiest way to use Menagerie from Python. It is published on PyPI, so the install is a single pip command:

pip install mujoco-menagerie

Once installed, the package exposes a load function and a get function. The README gives this exact example, using unitree_go2:

import mujoco_menagerie as mm

model = mm.load('unitree_go2')  # downloads once, compiles scene.xml
spec = mm.get('unitree_go2').spec()  # editable mujoco.MjSpec

The first call downloads the model the first time it is loaded, into a per-user cache, and compiles scene.xml. The second returns an editable mujoco.MjSpec, which is the path to take if you need to modify the model before compiling rather than just instantiate it.

If you want to look at a model without installing anything at all, the README offers a one-liner through uvx:

uvx mujoco-menagerie view unitree_go2

That opens the model straight from the command line. The alternative route, for people who prefer working from a checkout, is to clone the repository and run the Python viewer against a scene file:

git clone https://github.com/google-deepmind/mujoco_menagerie.git
python -m mujoco.viewer --mjcf mujoco_menagerie/unitree_go2/scene.xml

Note that the viewer command requires MuJoCo itself to be installed; the README says you can get it from PyPI with pip install mujoco. The minimum required MuJoCo version differs per model and is specified in each model's own README, which is the first thing to check if a scene fails to compile.

The grading system, and why it is a warning as much as a feature

Menagerie does not claim its models are accurate. The README says the goal is to eventually make all models as faithful as possible to the real system, that improving model quality is an ongoing effort, and that the current state of many models is not necessarily as good as it could be. That is an unusually candid statement for a curated library, and it should shape how you use it.

To set expectations, the project defines four grades. A+ means values are the product of proper system identification. A means values are realistic but have not been properly identified. B means stable, but some values are unrealistic. C means conditionally stable and can be significantly improved. The critical caveat is in the README itself: the grading system will be applied to each model once a proper system identification toolbox is created, and that toolbox is described as planned for release later in the year. Until then, the grades describe a scheme rather than a per-model label you can look up. Do not assume a model you download carries a grade today.

The practical consequence: a model that compiles, renders, and steps without exploding is not the same as a model whose mass, inertia, and friction values match the physical robot. For RL environment construction, visual demos, and kinematic planning, the first property is usually enough. For sim-to-real transfer of a contact-rich controller, it usually is not, and you would need your own identification work on top of whatever Menagerie ships.

Contributing, and what the Makefile actually runs

The contributor path is short by design. The README says you need uv installed as the only prerequisite, then gives two commands:

make install   # one-time: installs pre-commit + git hook
make all       # run every check CI runs (lint + format + license + XML + tests)

After make install, the README states that fast checks fire automatically on every git commit, and that make all should be run before pushing. The Makefile confirms the split: make check runs pre-commit across all files for lint, format, license, and XML checks, while make test runs the pytest model and structural test suite, which the Makefile itself labels slow. make all chains check, test, and python-test.

There are also maintenance targets worth knowing about. make gallery re-renders thumbnails and updates the gallery in README.md, which is why the model table in the README is marked as auto-generated by make gallery and not to be edited. make registry derives python/src/mujoco_menagerie/registry.json without archives, and make archives builds every model archive under python/dist-assets/ to test downloads locally. If you are adding a model, the README points to CONTRIBUTING.md for the full breakdown, and the build_registry.py, catalog.py, generate_gallery.py, format_xml.py, and regenerate_license.py scripts at the repository root are the tooling behind those targets.

Licensing is per model, not per repository

This is the trap. The repository-level license field is ambiguous, and the README makes clear why: each model directory contains its own LICENSE file that describes the copyright and licensing terms of that model. The gallery table in the README carries a License column per model, which confirms that terms vary across the collection. A model of a commercially sold robot may carry terms that differ from a model of a research platform.

There is tooling around this: regenerate_license.py exists at the repository root, and make check includes a license check in the pre-commit run. That keeps the files consistent, not permissive. If you plan to redistribute a model, ship it inside a product, or include it in a dataset, read the LICENSE file inside that specific model directory rather than the repository root. Nothing here is legal advice, and the README does not summarize the terms of any individual model.

Where Menagerie is the wrong tool

The clearest failure mode is expecting identified dynamics. The README's own framing, that many models are not necessarily as good as they could be, means Menagerie is a starting point for model parameters, not an authority on them. If your work depends on the simulated robot matching the real one at the level of contact forces or actuator response, you will be doing the identification yourself, and the grading table will not tell you which models need it most until the toolbox ships.

A second limitation is coverage. The MJX variants exist for some models and not others, per the README, so a GPU-accelerated MJX workflow may be blocked on the specific robot you need. A third is scope: Menagerie supplies models, not environments, controllers, or training code. If you want a task with rewards and a training loop, this repository does not provide one, and the models are inputs to that layer rather than a substitute for it. Finally, the minimum MuJoCo version is per model and lives in each model README, so a model can fail to compile on an older MuJoCo install with no repository-level version floor to warn you.

Menagerie compared with robot_descriptions

The README names one alternative directly: Menagerie models are also available through the third-party robot_descriptions package. The difference is one of scope rather than quality. robot_descriptions is a loader that pulls descriptions from many upstream sources, so it covers formats and robots outside MuJoCo's MJCF and outside what DeepMind curates. Menagerie is the curated source itself, with a single modeling format, a per-model LICENSE, a contributor pipeline with XML and license checks in CI, and the stated quality goal of faithfulness to the real system.

Choosing between them comes down to what you need. If you want one API that reaches many description formats and upstream repositories, robot_descriptions is the broader net, and it can serve you Menagerie models as one of its sources. If you want MJCF models that have passed a curated review and you care about the provenance and license of each individual model, going to Menagerie directly gives you the README, the LICENSE, and the generation notes per model without an intermediary. For a MuJoCo-only project, the direct route is the shorter one.

Editorial conclusion

Adopt Menagerie if you need robot MJCF files that compile and behave sensibly without hand-authoring them, especially for MuJoCo RL or manipulation work. Skip it if you need identified dynamics parameters for contact-rich control, because the README states many models are not as good as they could be. Before committing, read the README inside the specific model directory you plan to use and check its stated minimum MuJoCo version, and confirm the per-model LICENSE file matches how you intend to ship the model.

Frequently asked questions

Official sources

1. google-deepmind/mujoco_menagerie on GitHub
2. Issues
3. README
4. Releases