mujoco-stubs

An unofficial stub-only package providing type hints for MuJoCo, a physics engine for robotics and biomechanics.

The stubs were generated from MuJoCo 3.12.0 using pybind11-stubgen and corrected with the generation scripts in this repository. They are a best-effort aid to type checking and autocompletion, and may be incomplete or inaccurate. Consult the official MuJoCo documentation for runtime behavior.

Usage

Python 3.10 or newer is required. Install from PyPI:

pip install mujoco-stubs

This installs the stubs and their typing dependencies without installing or constraining MuJoCo. To also install a compatible MuJoCo runtime, use the extra:

pip install "mujoco-stubs[mujoco]"

The extra requires mujoco>=3.12.0,<3.13.0 and may change the installed MuJoCo version to satisfy that range. Type checkers that support PEP 561 discover the stubs automatically when your code imports mujoco.

The package is partial. Graphics typing focuses on Renderer, viewer handles, and public GLContext operations. Direct OpenGL/EGL/CGL bindings and internal modules such as mujoco._simulate and the gl_context backend selectors remain partially or wholly uncovered.

The stubs have been audited on both macOS (CGL) and Linux with EGL libraries available. Windows runtime auditing is not yet covered.

Versioning

The version of this package follows {mujoco_version}.{stub_revision}. For example, 3.12.0.1 is stub revision 1 generated from MuJoCo 3.12.0; 3.12.0.2 would contain further stub corrections. This release targets the MuJoCo 3.12 series. The optional mujoco extra enforces that version range; a plain installation leaves runtime version selection to you. The stub version number alone does not constrain MuJoCo.

Development

With uv installed, run the package validation:

uv run --locked --python 3.12 python scripts/validate.py

If you use just, just validate runs the same checks, just lint checks the validation code, and just build builds distributions.

just audit runs mypy's stubtest with commented allowlists for known native-binding differences and partial coverage.

License

Licensed under Apache-2.0. See NOTICE for MuJoCo and dm_control attribution and the origin of the generated declarations.