Installation — Native

Native installation needs more setup and is less reproducible than Docker. See System Requirements for supported simulator versions and source pins.

1. Install Prerequisites

Install 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

This guide targets Ubuntu 22.04 and Python 3.12. Its system Python is older, so install uv and its managed Python:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12
uv python find 3.12

Use Isaac Sim’s python.sh for SRB and simulator packages. uv supplies host Python 3.12.

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 https://github.com/AndrejOrsula/space_robotics_bench.git
cd space_robotics_bench
git submodule update --init --recursive

Without submodules, clone normally and initialize asset repos from your 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: For --source hf, replace <owner>/<repo> with your mirror’s repository IDs. Without a mirror, use the submodule commands above. Run remaining commands from the repository root.

3. Install NVIDIA Isaac Sim

Build Isaac Sim from source using the provided script:

ACCEPT_EULA=Y \
SRC_BRANCH=release/6.1 \
SRC_COMMIT_SHA=7c206f75bdadd9e05fc457f19863ca4c3f0cb693 \
  ./scripts/install_isaacsim.bash "$HOME/isaac-sim"

Set ACCEPT_EULA=Y only after reviewing and accepting NVIDIA’s license.

Environment Variables

Add these variables to your shell configuration. Copy the export VK_DRIVER_FILES=... line printed by the installer; it detects an existing Vulkan ICD or creates and reports one. Keep ~/.local/bin on PATH for the optional CLI shims installed there by default.

Bash and Zsh

cat >> ~/.bashrc << 'EOF'
# For Zsh, replace both ~/.bashrc references with ~/.zshrc.
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"
# Use the 6.1 asset root and profile printed by the installer. The default
# native install keeps assets beside the verified simulator checkout.
export ISAACSIM_ASSET_ROOT="$HOME/isaac-sim/assets"
export ISAACSIM_ASSET_ROOT_PROFILE="isaac-sim-6.1"
export OMNI_KIT_ALLOW_ROOT="1"
EOF
source ~/.bashrc

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 ISAACSIM_ASSET_ROOT "$HOME/isaac-sim/assets"
set -Ux ISAACSIM_ASSET_ROOT_PROFILE "isaac-sim-6.1"
set -Ux OMNI_KIT_ALLOW_ROOT "1"

4. Install NVIDIA Isaac Lab

SRC_BRANCH=release/3.0.0 \
SRC_COMMIT_SHA=fdc650c88dfd86aa158b9a1760b6537fef360555 \
  ./scripts/install_isaaclab.bash "$HOME/isaaclab"

This also resolves numpy 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"

It installs and verifies pinned SimForge (simforge[dev] 0.4.0 and simforge-foundry 0.3.1), then applies the Isaac Lab compatibility patch so native and container procedural assets match.

6. Install RL Frameworks (Optional)

Optional source installs. Most scripts need ISAACSIM_PYTHON; source your shell configuration first.

6a. DreamerV3

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

6b. TD-MPC2

Clones TD-MPC2 source; pyproject.toml installs its Python dependencies.

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

The script pins TD-MPC2 and applies SRB backports. SRB rejects a plain clone, which lacks the required Q-ensemble initialization fix.

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"

Pins upstream robomimic, applies the ADR-0032 lazy-language patch from srb/integrations/robomimic/patches/ as Docker does, and verifies the patched revision before installing. Offline imports then need no language-model download. Step 7 leaves this checkout in place; no SRB extra carries 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 the optional groups it lists; Git-pinned sources stay separate. Adjust it in pyproject.toml.

Git-pinned upstreams are excluded from extras because PyPI rejects direct references; install robomimic in step 6c. The optional v2e backend and E2VID operator are also excluded from all. Install them with pip 25.1 or newer, which supports --group from pyproject.toml:

"$ISAACSIM_PYTHON" -m pip install --upgrade 'pip>=25.1'
"$ISAACSIM_PYTHON" -m pip install --editable ".[event-v2e,event-reconstruction]" --group source-event-v2e --group source-event-reconstruction

Setup CLI

./scripts/setup_cli.bash

Installs srb, simforge, and space_robotics_bench shims in ~/.local/bin by default and configures detected shell completions. Set executable ISAACSIM_PYTHON and put the destination on PATH. Cache discovery uses it, then python3; argcomplete lookup order is Isaac Sim, system PATH, bundled package.

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

Hydra override completions need SRB cache files. Generate them, then install shell registrations:

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

Note: Hydra override completions require jq. The CLI remains available as "$ISAACSIM_PYTHON" -m srb if setup fails or you skip shims.

8. Verify Installation

See Troubleshooting for common issues.

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: 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

Expect a performance report with steps per second.

… continue with Basic Usage

Troubleshooting

“Failed to create any GPU devices”

VK_DRIVER_FILES does not point to a valid Vulkan ICD.

# 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

Set VK_DRIVER_FILES to the correct path in your shell configuration.

“Application failed to start”

DISPLAY is unset. 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.