mjlab: an Isaac Lab style API on top of MuJoCo Warp

What mjlab solves for robot learning teams

Isaac Lab gives reinforcement learning researchers a manager-based way to describe environments: managers for observations, rewards, terminations and events, each configured declaratively rather than written as one large step function. The cost is Isaac Sim, a heavy dependency that ties the stack to NVIDIA's Omniverse runtime. mjlab keeps the API shape and replaces the simulation layer with MuJoCo Warp, the GPU-accelerated version of MuJoCo. The stated goal is composable building blocks for environment design with minimal dependencies and direct access to native MuJoCo data structures.

The audience is narrow and specific. The README states that mjlab requires an NVIDIA GPU for training and that macOS is supported for evaluation only. That single sentence rules out a large group of potential users before they install anything. If you are training on a MacBook or on CPU-only cloud instances, this is not the framework for you. If you have a CUDA machine and you want MuJoCo's contact model under an Isaac Lab style configuration layer, the project targets exactly that gap.

How the manager-based API sits on MuJoCo Warp

The architecture is a layering, not a rewrite. mjlab depends on mujoco-warp and mujoco, both pinned in pyproject.toml at the 3.11 line, plus warp-lang for the kernel layer. On top of that sit the managers that shape an MDP, and on top of those sit task registrations with identifiers like Mjlab-Velocity-Flat-Unitree-G1. Training code never touches Warp kernels directly; it configures managers and lets the framework step the simulation on the GPU.

The dependency list is where the design shows. There is no Isaac Sim, no Omniverse, no simulator binary to install separately. The heavy entries are torch, warp-lang, mujoco-warp, rsl-rl-lib pinned at 5.5.1 for the RL side, and wandb for experiment tracking. The repository also ships a small forked utility directory, src/mjlab/utils/lab_api/, taken from NVIDIA Isaac Lab under BSD-3-Clause, which is how the manager API is reproduced without vendoring the whole upstream project.

One consequence worth naming: because the framework exposes native MuJoCo data structures, code written against it can read and write MuJoCo fields directly instead of going through an abstraction. That is a real advantage for debugging and for research that needs quantities the manager API does not surface. It also means your environment code is coupled to MuJoCo Warp's data layout, so porting a task back to Isaac Sim is not a configuration change.

Installing mjlab and running a first training job

The quickest path requires no installation at all. The README gives a one-line demo run through uvx, which fetches the package and executes the demo entry point. Expect a window or viewer session driven by the demo script rather than a training run.

uvx --from mjlab --refresh demo

For a real working copy, clone the repository and run the same demo from source. This is the path the README documents for source installs, and it is what you want if you intend to edit tasks.

git clone https://github.com/mujocolab/mjlab.git && cd mjlab
uv run demo

The README points to the Installation Guide for PyPI and Docker alternatives. The Dockerfile in the repository shows what that image contains: it starts from nvidia/cuda:12.8.0-runtime-ubuntu24.04, installs Python 3.13 through uv, syncs the locked dependency set, sets MUJOCO_GL=egl, exposes port 8080 and runs tests/smoke_test.py as its default command. If you build it yourself, make docker-build produces a mjlab:latest tag.

Training is a single command. The README's velocity-tracking example trains a Unitree G1 humanoid on flat terrain across 4096 parallel environments.

uv run train Mjlab-Velocity-Flat-Unitree-G1 --env.scene.num-envs 4096

Scaling to more than one GPU uses --gpu-ids with a bracketed list, which the README shows as "[0, 1]". Motion imitation follows the same shape but needs a motion registry name, and the README notes that preprocessing setup is covered in a separate guide.

uv run train Mjlab-Tracking-Flat-Unitree-G1 --registry-name your-org/motions/motion-name --env.scene.num-envs 4096

Before any of that, the README suggests sanity-checking the MDP with the built-in dummy agents. The zero agent sends zero actions and the random agent sends uniform random actions, which is a fast way to confirm that a task loads and steps without training anything.

uv run play Mjlab-Your-Task-Id --agent zero
uv run play Mjlab-Your-Task-Id --agent random

Evaluation during training pulls the latest checkpoint from Weights & Biases through --wandb-run-path, so the tracking service is part of the normal workflow rather than an optional extra.

Where mjlab is the wrong tool

The hardware requirement is the first hard boundary and the README states it plainly: an NVIDIA GPU for training, macOS for evaluation only. There is no documented CPU training path. The Makefile does define sync-cpu and a FORCE_CPU environment variable for the test suite, but that is test infrastructure, not a training mode, and the README does not present it as one.

Platform coverage beyond that is not documented in the README. Windows is not mentioned. The Dockerfile targets a CUDA runtime image, which implies Linux containers. If you need to train on a platform the README does not list, you are reading the Installation Guide and the issue tracker, not the front page.

There is a second, quieter limitation. mjlab reproduces the manager-based API, not the whole of Isaac Lab. Anything you rely on from Isaac Sim itself, whether a sensor model, a renderer feature or an asset pipeline, is not part of this dependency set. Teams with an existing Isaac Lab codebase should treat a move to mjlab as a port, and should expect the parts of their stack that touch the simulator to need rework. The citation block also matters here: the project asks that research using it cite an arXiv preprint, which is a normal expectation for a research framework but worth knowing before you build a course or a product on it.

Finally, the version pins are tight. mujoco and mujoco-warp are both constrained to the 3.11 line and rsl-rl-lib is pinned at exactly 5.5.1. That is good for reproducibility and less good if your project already depends on a different MuJoCo release.

mjlab against Isaac Lab and plain MuJoCo Warp

The obvious comparison is Isaac Lab itself, and the difference is the simulation backend plus the dependency footprint. Isaac Lab runs on Isaac Sim and brings the Omniverse stack with it. mjlab runs on MuJoCo Warp and brings torch, warp-lang and mujoco-warp. If your research depends on Isaac Sim's rendering or its sensor simulation, Isaac Lab is the one that has them. If your work is contact-rich manipulation or locomotion where MuJoCo's solver is the reference you trust, mjlab gives you that solver under an API you may already know. The project acknowledges the debt directly: the README thanks the Isaac Lab team, whose API design and abstractions mjlab builds upon.

The other comparison is MuJoCo Warp without any framework around it. Going direct means writing your own batching, your own reward and termination logic, and your own training loop wiring. mjlab supplies the manager layer, task registrations, RL integration through rsl-rl-lib, and a set of command-line entry points (train, play, demo, list-envs, viz-nan, export-scene) that make a task runnable without writing a harness. The trade is that you accept the manager abstractions and the pinned dependency set. For a quick experiment where you want full control over the step function, direct MuJoCo Warp is less machinery. For a project with several tasks and several people, the manager layer is what keeps the codebase from fragmenting.

Maintenance, upgrades and the Apache-2.0 terms

The repository is not archived, and the last push was on 2026-09-23, one day before this writing. Release history shows v1.6.0 on 2026-08-09, preceded by v1.5.3 on 2026-07-22 and v1.5.2 on 2026-07-17, and pyproject.toml carries version 1.6.0. That is a short release cadence with patch releases between minor ones, which suggests fixes land quickly but also that pinning a version for a long experiment is wise.

Upgrade cost is dominated by the simulator pins. mujoco-warp is constrained with a compatible-release operator at 3.11.0, and mujoco follows the same pattern, so a MuJoCo 3.12 upgrade is not something you get by running a sync. The project tracks upstream closely enough that the README thanks the MuJoCo Warp team for implementing features on request, which cuts both ways: features you need may arrive, but they arrive on the upstream schedule.

Licensing is Apache-2.0 for the project as a whole, with one carve-out the README calls out explicitly. The directory src/mjlab/utils/lab_api/ contains utilities forked from NVIDIA Isaac Lab under BSD-3-Clause, and the README states that forked components retain their original licenses, with details in the file headers. If you redistribute mjlab or build on it, that directory is the one to read before you assume a single licence covers everything. This is a description of what the repository says, not legal advice.

Editorial conclusion

mjlab fits researchers who already think in Isaac Lab terms and want MuJoCo Warp underneath, or who need multi-GPU training without a full Isaac Sim install. Skip it if you have no NVIDIA GPU for training, need to train on macOS, or depend on Isaac Sim features the framework does not carry over. Before committing, check the Installation Guide for the PyPI and Docker paths, confirm your GPU matches the CUDA extra used by make sync, and run uv run play on your own task with --agent zero to verify the MDP loads.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mujocolab/mjlab on GitHub
3. Project website
4. README
5. Releases