Installation — Native

This guide covers installing SRB natively on your system without containerization. Although this approach simplifies development, it requires more manual setup and decreases reproducibility.

1. Install Prerequisites

Install the required system packages:

sudo apt-get update
sudo apt-get install -y git git-lfs gcc-11 g++-11 cmake build-essential curl unzip xz-utils python3 jq

mkdir -p ~/.local/bin /tmp/git-lfs-install
curl -sSL https://github.com/git-lfs/git-lfs/releases/download/v3.6.1/git-lfs-linux-amd64-v3.6.1.tar.gz -o /tmp/git-lfs.tar.gz
tar xzf /tmp/git-lfs.tar.gz -C /tmp/git-lfs-install
cp /tmp/git-lfs-install/git-lfs-*/git-lfs ~/.local/bin/
rm -rf /tmp/git-lfs.tar.gz /tmp/git-lfs-install

2. Clone the Repository

git clone --recurse-submodules https://github.com/AndrejOrsula/space_robotics_bench.git
cd space_robotics_bench

If you prefer not to use git submodules, you can clone normally and then initialize asset repos from a Hugging Face mirror:

git clone https://github.com/AndrejOrsula/space_robotics_bench.git
cd space_robotics_bench
./assets/update.bash --source hf --repo-id <owner>/<repo>
./assets/update.bash --source hf --repo-id <owner>/<graphics-repo> --path docs/src/_graphics

Note: The --source hf path is for cloning from a Hugging Face mirror — substitute your own mirror’s repository IDs for <owner>/<repo>. If you do not have a mirror, prefer the default --recurse-submodules clone above, which needs no substitution.

All remaining commands in this guide assume your current working directory is the repository root.

3. Install NVIDIA Isaac Sim

Build Isaac Sim from source using the provided script:

./scripts/install_isaacsim.bash "$HOME/isaac-sim"

Environment Variables

Set the following environment variables in your shell configuration. Use the values printed by the install script — particularly VK_DRIVER_FILES, which is auto-detected for your system.

Also ensure ~/.local/bin is on your PATH, because the optional CLI setup step installs wrapper executables there by default.

bash

cat >> ~/.bashrc << 'EOF'
export PATH="$HOME/.local/bin:$PATH"
export ISAACSIM_PYTHON="$HOME/isaac-sim/python.sh"
export ISAACSIM_PATH="$HOME/isaac-sim"
export ISAAC_PATH="$HOME/isaac-sim"
export CARB_APP_PATH="$HOME/isaac-sim/kit"
export EXP_PATH="$HOME/isaac-sim/apps"
export LD_PRELOAD="$HOME/isaac-sim/kit/libcarb.so"
export VK_DRIVER_FILES="/usr/share/vulkan/icd.d/nvidia_icd.json"
export OMNI_SERVER="https://omniverse-content-staging.s3-us-west-2.amazonaws.com/Assets/Isaac/6.0"
export OMNI_KIT_ALLOW_ROOT="1"
EOF
source ~/.bashrc

zsh

cat >> ~/.zshrc << 'EOF'
export PATH="$HOME/.local/bin:$PATH"
export ISAACSIM_PYTHON="$HOME/isaac-sim/python.sh"
export ISAACSIM_PATH="$HOME/isaac-sim"
export ISAAC_PATH="$HOME/isaac-sim"
export CARB_APP_PATH="$HOME/isaac-sim/kit"
export EXP_PATH="$HOME/isaac-sim/apps"
export LD_PRELOAD="$HOME/isaac-sim/kit/libcarb.so"
export VK_DRIVER_FILES="/usr/share/vulkan/icd.d/nvidia_icd.json"
export OMNI_SERVER="https://omniverse-content-staging.s3-us-west-2.amazonaws.com/Assets/Isaac/6.0"
export OMNI_KIT_ALLOW_ROOT="1"
EOF
source ~/.zshrc

fish

fish_add_path "$HOME/.local/bin"
set -Ux ISAACSIM_PYTHON "$HOME/isaac-sim/python.sh"
set -Ux ISAACSIM_PATH "$HOME/isaac-sim"
set -Ux ISAAC_PATH "$HOME/isaac-sim"
set -Ux CARB_APP_PATH "$HOME/isaac-sim/kit"
set -Ux EXP_PATH "$HOME/isaac-sim/apps"
set -Ux LD_PRELOAD "$HOME/isaac-sim/kit/libcarb.so"
set -Ux VK_DRIVER_FILES "/usr/share/vulkan/icd.d/nvidia_icd.json"
set -Ux OMNI_SERVER "https://omniverse-content-staging.s3-us-west-2.amazonaws.com/Assets/Isaac/6.0"
set -Ux OMNI_KIT_ALLOW_ROOT "1"

4. Install NVIDIA Isaac Lab

./scripts/install_isaaclab.bash "$HOME/isaaclab"

The script also resolves numpy version conflicts and installs array_api_compat.

5. Install Blender 4.5 with SimForge

Official instructions: Blender — Install from blender.org

./scripts/install_blender.bash "$HOME/blender"

The script downloads Blender, creates a symlink at ~/.local/bin/blender, and installs SimForge into Blender’s bundled Python.

6. Install RL Frameworks (Optional)

The following frameworks require source installation. Each is optional — install only the ones you need. Most scripts require ISAACSIM_PYTHON to be set, so source your shell configuration first if you haven’t already.

6a. DreamerV3

./scripts/install_dreamerv3.bash "$HOME/dreamerv3"

6b. TD-MPC2

TD-MPC2 is not pip-installed — only its source code is cloned. Python dependencies (tensordict, torchrl, etc.) are installed later via pyproject.toml.

./scripts/install_tdmpc2.bash "$HOME/tdmpc2"

The script pins upstream TD-MPC2 and applies the recorded backports from srb/integrations/tdmpc2/patches/ (currently upstream’s Q-ensemble weight-initialization fix, which otherwise leaves the entire Q ensemble on PyTorch’s default initialization). Upstream’s dependency-pin commit is deliberately not adopted, because it would downgrade the Torch/TensorDict/TorchRL matrix that Isaac Sim provides. SRB refuses to construct a TD-MPC2 agent on a checkout without the backport, so use this script (or reproduce the pin exactly as the error message describes) rather than a plain git clone.

Set the TDMPC2_PATH environment variable:

# Bash
echo "export TDMPC2_PATH='$HOME/tdmpc2/tdmpc2'" >> ~/.bashrc && source ~/.bashrc

# Zsh
echo "export TDMPC2_PATH='$HOME/tdmpc2/tdmpc2'" >> ~/.zshrc && source ~/.zshrc

# Fish
set -Ux TDMPC2_PATH "$HOME/tdmpc2/tdmpc2"

6c. robomimic

./scripts/install_robomimic.bash "$HOME/robomimic"

6d. rsl_rl

./scripts/install_rsl_rl.bash "$HOME/rsl_rl"

7. Install the Space Robotics Bench

"$ISAACSIM_PYTHON" -m pip install --editable ".[all]"

Note: The all extra installs optional dependencies for all workflows. See pyproject.toml to adjust.

Setup CLI

./scripts/setup_cli.bash

The setup script copies srb, simforge, and space_robotics_bench shims into ~/.local/bin by default and configures shell completions for detected shells.

Requirements for this step:

• ISAACSIM_PYTHON must already be set and executable
• the destination directory (default: ~/.local/bin) must already be on your PATH
• python3 is used to discover the SRB cache directory for Hydra override completions
• register-python-argcomplete is resolved from Isaac Sim first, then from your system PATH

# Only regenerate completions for specific shells
./scripts/setup_cli.bash --completions-only bash zsh fish

Hydra override completions depend on the SRB cache files. Generate them once after installation, then install the shell registrations:

srb completions generate
srb completions install
exec "$SHELL" -l

Note: jq is required for Hydra override completions. The srb CLI is always accessible via "$ISAACSIM_PYTHON" -m srb even if the setup script fails or you skip shim installation.

8. Verify Installation

If you encounter issues, refer to the Troubleshooting section below.

Isaac Sim

"$ISAACSIM_PYTHON" -c "
from isaacsim import SimulationApp
sim = SimulationApp({'headless': True})
print('Isaac Sim OK — is_running:', sim.is_running())
sim.close()
"

Note: The first launch takes longer due to shader compilation.

Isaac Lab

"$ISAACSIM_PYTHON" -m pip show isaaclab

Blender

blender --version

Space Robotics Bench

"$ISAACSIM_PYTHON" -m srb --help
command -v srb
srb --help
"$ISAACSIM_PYTHON" -m srb cache update

Run a Quick Simulation

"$ISAACSIM_PYTHON" -m srb agent zero --headless -e sample_collection --cfg ignore --perf --perf_duration 10

You should see a performance report with steps per second at the end.

… continue with Basic Usage

Troubleshooting

“Failed to create any GPU devices”

VK_DRIVER_FILES does not point to a valid Vulkan ICD file.

# Check current value
ls -la "$VK_DRIVER_FILES"

# Find the correct path
find /etc/vulkan /usr/share/vulkan -name "nvidia_icd.json" 2>/dev/null

Update VK_DRIVER_FILES in your shell configuration to the correct path.

“Application failed to start”

The DISPLAY environment variable is not set. For headless servers with a virtual display:

# Bash/Zsh
echo 'export DISPLAY=:99' >> ~/.bashrc  # or ~/.zshrc

# Fish
set -Ux DISPLAY :99

numpy version conflicts

The install_isaaclab.bash script resolves these automatically. If errors reappear after manual package changes:

"$ISAACSIM_PYTHON" -m pip install "numpy>=2.1" array_api_compat

Extras

Development

To improve your development experience, consider configuring your IDE.