Guide · verified against the official README

How to set up MotionBricks: clone, checkpoints, first demo

Nine commands from an empty folder to a keyboard-driven G1 humanoid — with the two traps that bite almost everyone: the skipped-LFS checkpoints and the 1 KB pointer files. Every command below is copied verbatim from the official README; only the order of explanation differs.

Requirements

  • Python 3.10+
  • A CUDA-capable GPU
  • Git LFS — checkpoints, meshes and gallery GIFs are LFS-tracked

MotionBricks ships as a subproject of GR00T-WholeBodyControl: you clone the parent monorepo and work inside motionbricks/.

1 · Clone the repository

git lfs install

The parent repo skips MotionBricks pretrained checkpoints by default so a normal monorepo clone does not automatically download the extra ~2.2 GB. Source-only clone (fine if you just want the code):

git clone https://github.com/NVlabs/GR00T-WholeBodyControl.git
cd GR00T-WholeBodyControl/motionbricks

2 · Pull the checkpoints explicitly

For the interactive demo you need the weights and the G1 meshes. From the repo root:

git clone https://github.com/NVlabs/GR00T-WholeBodyControl.git
cd GR00T-WholeBodyControl
git lfs pull --include="motionbricks/out/**" --exclude=""
git lfs pull --include="motionbricks/assets/skeletons/g1/meshes/**" --exclude=""  # needed for interactive demo
cd motionbricks

3 · Verify the files actually downloaded

This is the step people skip and then spend an hour debugging. Checkpoint files must have real sizes:

ls -lh out/G1-clip.ckpt                                     # ~7.5 MB
ls -lh out/motionbricks_vqvae/version_1/checkpoints/*.ckpt  # ~273 MB
ls -lh out/motionbricks_pose/version_1/checkpoints/*.ckpt   # ~1.6 GB
ls -lh out/motionbricks_root/version_1/checkpoints/*.ckpt   # ~391 MB
If a checkpoint is ~1 KB, it is a Git LFS pointer, not the model.

From the repo root, fetch the real bytes and re-check:

git lfs pull --include="motionbricks/out/**" --exclude=""

Quick sanity check on a suspect file: head -c 60 out/motionbricks_pose/version_1/checkpoints/<file>.ckpt — a real checkpoint starts with binary data; a pointer file starts with version https://git-lfs.github.com/spec/v1.

Checkpoint inventory (official sizes)
FileExpected size
out/G1-clip.ckpt~7.5 MB
out/motionbricks_vqvae/version_1/checkpoints/*.ckpt~273 MB
out/motionbricks_pose/version_1/checkpoints/*.ckpt~1.6 GB
out/motionbricks_root/version_1/checkpoints/*.ckpt~391 MB

4 · Install dependencies

# Create environment
conda create -n motionbricks python=3.10 -y
conda activate motionbricks

# Install dependencies
pip install -e .

# Linux only: needed for keyboard input and MuJoCo key-grab workaround
pip install pynput python-xlib

5 · Run the interactive G1 demo

DISPLAY=:1 python scripts/interactive_demo_g1.py

This launches the MuJoCo viewer with the G1 robot; drive it live from the keyboard, and hold the left mouse button to orbit the look-at direction. The DISPLAY=:1 prefix assumes an X11 session on GPU 1's display — drop or adjust it for your setup. Full key table and camera behavior: G1 demo guide.

Known issues (verbatim from the README)

  • Linux/X11 only: The keyboard key-grab workaround requires X11 (python-xlib). On Wayland, macOS, or Windows, some MuJoCo keyboard shortcuts may conflict with the controller keys. Keep the terminal focused (not the MuJoCo window) as a workaround.
  • PYTORCH_JIT=0 disables key grabs: Running with PYTORCH_JIT=0 interferes with the X11 key-grab workaround. If you need PYTORCH_JIT=0, keep the terminal focused instead.
  • Keyboard package differs by OS: The pynput package is required for keyboard input on Linux/macOS. On Windows, the keyboard package is used instead.

Setup FAQ

How to set up Motion Bricks (NVIDIA) step by step?
Install Git LFS, clone the GR00T-WholeBodyControl monorepo, pull the MotionBricks checkpoints explicitly with git lfs pull (the parent repo skips them by default), create a Python 3.10 conda environment, pip install -e . inside motionbricks/, then run the interactive G1 demo script. The full copy-paste commands are above on this page.
Does MotionBricks need a GPU?
Yes — a CUDA-capable GPU is a stated requirement in the official README, along with Python 3.10 and Git LFS. A CPU-only machine can read and build the repo but cannot run the interactive demo as documented.
Why are my checkpoint files only 1 KB?
They are Git LFS pointer files, not the real weights — the classic trap because the parent monorepo intentionally skips MotionBricks checkpoints during a normal clone to avoid the ~2.2 GB download. From the repo root run: git lfs pull --include="motionbricks/out/**" --exclude="" and verify sizes again with ls -lh.
How much disk space does the full MotionBricks demo need?
About 2.2 GB of checkpoints (VQVAE ~273 MB, pose ~1.6 GB, root ~391 MB, G1-clip ~7.5 MB) plus the repository itself with LFS-tracked GIFs and mesh assets. Budget roughly 5 GB of working space.
Can I run the demo on Windows?
The keyboard key-grab workaround is Linux/X11-only, so on Windows (and macOS/Wayland) some MuJoCo shortcuts may conflict with controller keys. The official workaround: keep the terminal focused instead of the MuJoCo window, and install the keyboard Python package (used on Windows in place of pynput).
MotionBricks demo download — is there a standalone installer?
No standalone installer exists. The official distribution is the GitHub repository with Git LFS assets; anything packaged elsewhere is unofficial. Follow the clone-and-lfs-pull commands on this page.