Installation

Installation#

wbc-mjlab extends mjlab and installs with it. Use a source checkout to run the bundled samples and the Studio, or add it as a dependency of your own project.

System requirements#

Training: Linux + NVIDIA GPU (CUDA 12.8+ recommended, same as mjlab)
Evaluation: Linux, macOS, or Windows (WSL) with CPU PyTorch
Python: 3.10–3.13

From source (recommended)#

For hacking on wbc_mjlab or running the bundled samples.

uv

Install uv if needed, then:

git clone https://github.com/wbc-mjlab/wbc-mjlab.git && cd wbc-mjlab
make sync

make sync runs uv sync --extra cu128 --group dev (CUDA PyTorch + dev tools). CPU-only / macOS evaluation:

make sync-cpu

uv run uses the locked environment in uv.lock (same workflow as mjlab).

pip

git clone https://github.com/wbc-mjlab/wbc-mjlab.git && cd wbc-mjlab
pip install -e ".[cu128]"

CPU-only / macOS:

pip install -e ".[cpu]"

You are responsible for a CUDA-capable PyTorch build when training on GPU.

Verify#

uv

uv run wbc-mjlab-list-envs

pip

Activate your virtualenv, then:

wbc-mjlab-list-envs

The output lists the robot g1 and the tasks Wbc-G1, Wbc-G1-Zest and friends.

Optional extras#

Extra / group	Purpose
`cu128`	CUDA 12.8 PyTorch (Linux training; default for `make sync`)
`cpu`	CPU PyTorch (evaluation, macOS, WSL smoke tests; `make sync-cpu`)
`dev` (uv group)	pytest, ruff, pre-commit
`docs` (uv group)	Sphinx site (`make docs`)

Build the documentation locally: docs/BUILDING.md.

Use as a dependency#

Add wbc-mjlab to an existing project (PyPI or local checkout). Ensure your environment has a CUDA or CPU PyTorch build when training on GPU (see mjlab installation guide).

uv

PyPI:

uv add wbc-mjlab mjlab

From GitHub:

uv add "wbc-mjlab @ git+https://github.com/wbc-mjlab/wbc-mjlab"

Editable local checkout:

uv add --editable /path/to/wbc-mjlab

pip

PyPI:

pip install mjlab wbc-mjlab

From GitHub:

pip install "wbc-mjlab @ git+https://github.com/wbc-mjlab/wbc-mjlab"

Editable local checkout:

pip install -e /path/to/wbc-mjlab

Local mjlab checkout (optional)#

When developing alongside a sibling mjlab repo, pin mjlab in pyproject.toml:

[tool.uv.sources]
mjlab = { path = "../../mjlab", editable = true }

uv lock && make sync

Remove the override before publishing the lockfile for PyPI-only users.

Next steps#

Quickstart

Train on the samples and watch a first policy.