This guide walks through a fresh install of RLDX-1 on a Linux machine with an NVIDIA GPU. The short version is at the top; subsequent sections cover simulator environments, developer tooling, and common pitfalls.
There are two install paths. Pick the one that matches your GPU:
| Path | Tool |
|---|---|
| Standard install | uv |
| SM_120 (RTX 5090 / Blackwell) | pixi |
# Standard install
git clone https://github.com/RLWRLD/RLDX-1.git
cd RLDX-1
uv sync --python 3.10
uv pip install -e .
python -c "import rldx; print(rldx.__version__)"# RTX 5090 / Blackwell (SM_120) — flash-attn must be built from source
git clone https://github.com/RLWRLD/RLDX-1.git
cd RLDX-1
pixi install
pixi run --environment rldx postinstall
pixi run --environment rldx python -c "import rldx; print(rldx.__version__)"If import rldx prints the installed rldx version (no import error) you are done for training and inference
against pre-trained checkpoints. Simulator eval stacks install separately
(see Simulator environments).
| Requirement | Version | Why |
|---|---|---|
| Linux | x86_64 | The model has only been exercised on Linux. |
| Python | 3.10.* (pinned) |
pyproject.toml constrains requires-python. |
| CUDA toolkit | 12.x | Needed to build flash-attn==2.7.4.post1. |
| NVIDIA driver | supports CUDA 12 | For torch==2.7.0 + flash-attn. |
| uv | >= 0.8.4 |
Dependency + virtualenv manager (Standard path). |
| pixi | >= 0.40 |
Conda-backed env manager (SM_120 path only). |
git / git-lfs |
recent | Submodules + HF LFS assets. |
Install uv if you do not already have it:
curl -LsSf https://astral.sh/uv/install.sh | shInstall pixi only if you are on the SM_120 path:
curl -fsSL https://pixi.sh/install.sh | shDefault path. flash-attn ships prebuilt wheels and uv sync installs
them directly without compilation. Use the
SM_120 path instead if you're on
RTX 5090 / Blackwell.
git clone https://github.com/RLWRLD/RLDX-1.git
cd RLDX-1
uv sync --python 3.10 # creates .venv and resolves deps
uv pip install -e . # installs the rldx package editableuv sync materialises the environment described by pyproject.toml,
including the [tool.uv.extra-build-dependencies] override that pins
torch==2.7.0 + numpy==1.26.4 at build time for flash-attn. The
resulting virtualenv lives at .venv/ and is activated automatically
by every uv run call.
# Python import smoke test — should print the installed rldx version (no ImportError)
uv run python -c "import rldx; print(rldx.__version__)"
# HuggingFace registry smoke test — should print "<class 'rldx.model.core.processing_rldx.RLDXProcessor'>"
uv run python -c "
import rldx
from transformers.models.auto.processing_auto import PROCESSOR_MAPPING
print(PROCESSOR_MAPPING._extra_content[rldx.RLDXConfig])
"flash-attn upstream does not publish prebuilt wheels for sm_120. The
Standard path's uv sync therefore fails on RTX 5090 with a missing
wheel error. The pixi path solves this by providing CUDA 12.8 toolkit
through the nvidia conda channel and compiling flash-attn from source
with TORCH_CUDA_ARCH_LIST=sm_120 baked into the env activation.
git clone https://github.com/RLWRLD/RLDX-1.git
cd RLDX-1
# Resolve and install the pixi-managed conda + PyPI environment.
pixi install
# Run the chained postinstall task — builds flash-attn from source for
# sm_120 and editable-installs the rldx package against the pixi torch.
pixi run --environment rldx postinstallThe postinstall task chains install-flash-attn (source build) before
pip install -e . --no-deps so a single command bootstraps the entire
env. TORCH_CUDA_ARCH_LIST=sm_120 is set both in
[feature.rldx.tasks.install-flash-attn] and in
[feature.rldx.activation] so any subsequent pixi run keeps the same
arch target.
# Python import smoke test — should print the installed rldx version (no ImportError)
pixi run --environment rldx python -c "import rldx; print(rldx.__version__)"
# flash-attn was built against the pixi torch and targets sm_120
pixi run --environment rldx python -c "
import torch
from flash_attn import flash_attn_func
print(torch.__version__, torch.cuda.get_device_capability())
"pixi.tomlpins torch 2.8.0 + cu128 (vs the uv path'storch 2.7.0). The two environments are deliberately separate; do not mix them.- The first
pixi run --environment rldx postinstalltakes 10-20 minutes because flash-attn compiles from source. Subsequent runs reuse the cached build. - If you are not on Blackwell, prefer the Standard install — pixi will work but pulls a larger conda payload (CUDA 12.8 toolkit) than uv needs.
Simulator eval stacks are maintained as git submodules under
external_dependencies/. They are optional — you only need the ones
that match the benchmarks you want to run — and most of them have their
own Python environments to avoid dependency conflicts with the main
training env.
# Pull the submodules you need
git submodule update --init external_dependencies/robocasa
git submodule update --init external_dependencies/LIBERO
git submodule update --init external_dependencies/SimplerEnvbash rldx/eval/sim/robocasa/setup_RoboCasa.shThe setup script creates a separate robocasa_uv/.venv under
rldx/eval/sim/robocasa/ and installs robocasa, robosuite, and mujoco
into that venv. The robocasa eval scripts (for example
run_scripts/eval/robocasa_kitchen/eval_robocasa.sh) explicitly invoke
that venv's Python so the main training env is untouched.
bash rldx/eval/sim/LIBERO/setup_libero.shSeparate venv at rldx/eval/sim/LIBERO/libero_uv/.venv.
bash rldx/eval/sim/SimplerEnv/setup_SimplerEnv.shbash rldx/eval/sim/GR00T-WholeBodyControl/setup_GR00T_WholeBodyControl.shRequires git-lfs and pulls a large amount of assets. The section
and script keep their upstream GR00T-WholeBodyControl name because
this is an unmodified external dependency that RLDX-1 only consumes at eval time.
For anyone editing the code rather than only consuming it, also install
the optional dev extra and set up the pre-commit hooks:
uv pip install -e ".[dev]"
uv tool install ruff
uv tool install pre-commit
pre-commit installThe pre-commit config (.pre-commit-config.yaml) runs the same
ruff check and ruff format --check steps that CI enforces, scoped to
rldx/. Run them against the whole tree ad-hoc with:
pre-commit run --all-filesThe wheel is compiled on first install and needs the CUDA toolkit,
not just a matching driver. Make sure nvcc --version works on the
machine, and that the version matches the version torch was built
against. On RTX 5090 (Blackwell) follow the
SM_120 install — the pixi env ships
the CUDA 12.8 toolkit so this error cannot occur.
Expected on first install: the wheel is compiled from source against your local torch build. Subsequent installs reuse the cached wheel. On RTX 5090 the SM_120 source build always runs (no prebuilt wheel exists upstream), so plan for the 10-20 minute first install.
The default uv sync pulled the prebuilt flash-attn wheel which only
ships kernels for SM_80 and SM_90. On Blackwell that wheel imports but
crashes at the first kernel launch. Switch to the
SM_120 install (pixi) — it builds
flash-attn from source with TORCH_CUDA_ARCH_LIST=sm_120.
The driver is missing or the LD_LIBRARY_PATH does not point at the
NVIDIA userspace libraries. On a typical Ubuntu install the fix is to
add /usr/lib/x86_64-linux-gnu to LD_LIBRARY_PATH, or to invoke the
Python interpreter inside an NVIDIA container.
Several code paths download the Qwen3-VL backbone or the reference
RLDX-1 checkpoint from the Hugging Face Hub on first use. Either run the
initial pull online, or pre-download the checkpoint to
$HF_HOME/hub/models--... before switching to offline mode.
The HuggingFace AutoProcessor registry is populated as a side effect
of import rldx. If you import inner modules directly without touching
rldx first, the class is not registered. The fix is always a one-line
import rldx before any AutoProcessor.from_pretrained(...) call.
training.md— run fine-tuning and mid-trainingevaluation.md— run LIBERO / RoboCasa / SIMPLER / GR-1 evalsinference_server.md— serve a checkpoint (ZeroMQ canonical / WebSocket alt)architecture.md— high-level model walkthrough