Installation

Installation#

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

wbc-mjlab extends mjlab. Install mjlab’s stack via one of the paths below.

From source (development)#

For hacking on wbc_mjlab or running the bundled samples.

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).

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.

Verification#

uv run wbc-mjlab-list-envs

Activate your virtualenv, then:

wbc-mjlab-list-envs

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).

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

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.

After install#

uv run wbc-mjlab-data-to-npz --robot g1 --dataset samples
uv run wbc-mjlab-train --task Wbc-G1 --dataset samples
uv run wbc-mjlab-play --task Wbc-G1 --dataset samples

With your virtualenv active:

wbc-mjlab-data-to-npz --robot g1 --dataset samples
wbc-mjlab-train --task Wbc-G1 --dataset samples
wbc-mjlab-play --task Wbc-G1 --dataset samples

Bundled motion credits: data/g1/samples/README.md in the repository.

See Quickstart: install → convert → train → play for the full end-to-end workflow.