Installation
Requirements, pip and from-source installs, the optional extras, and ROCm setup for AMD GPUs.
Requirements
- Python >= 3.12. Versions 3.12 and 3.13 are verified in continuous integration.
- Linux or macOS for the MuJoCo backend. Both are exercised in continuous integration.
Install with pip
pip install so101-nexusInstall from source
Clone the repository, then sync with uv:
git clone https://github.com/johnsutor/so101-nexus.git
cd so101-nexus
uv syncVerify the install
import gymnasium as gym
import so101_nexus.mujoco # registers the MuJoCo env ids
env = gym.make("MuJoCoPickLift-v1")
print("Installation OK")
env.close()Extras
The base install ships the MuJoCo backend and the environment API. Everything else is opt-in.
| Extra | Adds | Install |
|---|---|---|
teleop | Gradio demonstration recorder: lerobot[feetech], gradio, plotly, opencv-python | pip install "so101-nexus[teleop]" |
decomp | Measured convex decomposition of YCB collision meshes (coacd, rtree, threadpoolctl). Without it YCB collision geometry falls back to a single convex hull. The packages ship wheels for the supported platforms | pip install "so101-nexus[decomp]" |
viz | Pillow image labels and high-quality resizing in visualization helpers | pip install "so101-nexus[viz]" |
train | Torch training dependencies for the PPO and BC examples | pip install "so101-nexus[train]" |
warp | GPU-parallel MuJoCo Warp backend. Needs an NVIDIA GPU and CUDA >= 12.8 | pip install "so101-nexus[warp]" |
rocm | PyTorch from AMD's ROCm 7.2 wheel index. See below | uv sync --extra train --extra rocm --no-default-groups |
Extras combine: pip install "so101-nexus[teleop,train]".
Try without installing
uvx runs the teleop recorder in an ephemeral environment with no permanent install:
uvx --from "so101-nexus[teleop]" so101-nexus teleopTraining on an AMD GPU (ROCm)
The rocm extra installs PyTorch from the ROCm 7.2 wheel index instead of the default CUDA build, on Linux x86_64:
uv sync --extra train --extra rocm --no-default-groups--no-default-groups skips the dev dependency group. dev pins lerobot<0.6 for the test suite, which in turn forces torch<2.11, a range incompatible with the ROCm 7.2 torch build. For the same reason uv rejects combining rocm with teleop, dev, or test.
rocm affects MuJoCo-backend training only, meaning behavior cloning and PPO on CPU-simulated environments. It does not enable the Warp backend: Warp is built on NVIDIA Warp, which has no ROCm/AMD support and always requires a CUDA GPU.
Warp box collision patch
The optional patch in patches/mujoco-warp-3.13.0/ replaces box-pair collision detection with the CPU SAT, clipping, and edge algorithm.
It preserves other collision dispatch and uses double-precision intermediates with float32 inputs and outputs.
The normal warp extra does not include this patch. The grasp retention profile requires a separate physics configuration.
From a SO101-Nexus source checkout, build the patched dependency and install it in a separate environment:
nexus_root="$PWD"
engine_build=$(mktemp -d)
cd "$engine_build"
curl -fL -o mujoco_warp-3.13.0.tar.gz \
https://files.pythonhosted.org/packages/3f/1a/acc6851ba3b6d2e51d4af0ddb5d1924618c8293512a39abe8521a6f56a5d/mujoco_warp-3.13.0.tar.gz
echo '5d0a25560fed1b6735138159bac6d138cf123d2007e81e1f86304cf15182506c mujoco_warp-3.13.0.tar.gz' | sha256sum --check
tar -xzf mujoco_warp-3.13.0.tar.gz
cd mujoco_warp-3.13.0
git apply --check "$nexus_root/patches/mujoco-warp-3.13.0/box_box_cpu_sat_port_double.patch"
git apply "$nexus_root/patches/mujoco-warp-3.13.0/box_box_cpu_sat_port_double.patch"
uv build --wheel --out-dir "$engine_build/wheels"
uv venv --python 3.12 "$engine_build/venv"
uv pip install --python "$engine_build/venv/bin/python" \
-e "${nexus_root}[warp]" pytest \
"mujoco==3.13.0" "warp-lang==1.15.0" "torch==2.9.1" \
"$engine_build/wheels/mujoco_warp-3.13.0-py3-none-any.whl"
"$engine_build/venv/bin/python" -m pytest -q \
"$nexus_root/patches/mujoco-warp-3.13.0/tests/test_patched_box_collision.py"
BOX_TEST_DEVICE=cuda:0 "$engine_build/venv/bin/python" -m pytest -q \
"$nexus_root/patches/mujoco-warp-3.13.0/tests/test_patched_box_collision.py"The standalone tests compare contact geometry and normal force against CPU MuJoCo for thin fingers, aligned faces, and edge contact. CUDA tests also exercise captured graphs. The stock dependency fails the thin-finger and edge cases.
Use this environment's Python executable for runs with the patched engine.
A normal project uv sync or uv run can restore the stock dependency from the lockfile.
Restart the process after installation to rebuild models and CUDA graphs.
The patch targets only mujoco-warp==3.13.0. Identical collision algorithms do not imply identical trajectories or measured hardware behavior.