---
name: install-environment
description: Use when a user needs a full simready-benchmark install from zero — Python 3.12 venv, framework packages, engines.toml via the setup wizard, and a first test run. Covers Windows and Linux (Ubuntu). For repairing engines.toml only, use configure-engines-toml instead.
license: Apache-2.0
compatibility: Requires network access to NVIDIA PyPI (Artifactory or pypi.nvidia.com for Isaac). Git access to gitlab-master.nvidia.com if cloning simready_foundations.
metadata:
  author: NVIDIA
  library: simready_benchmark
  version: "2026.05"
---

## Confirm the Installed Version

If the framework is already installed, run `simready-benchmark --version` and treat
`simready-benchmark --help` as authoritative. This skill ships inside the wheel at
`simready-benchmark --skills-path`; prefer that copy over cached text.

## How to Use This Skill

Walk the user through setup one step at a time. Validate paths on disk before
writing configuration. After the wizard, run `simready-benchmark --show-config` before
the first asset run.

For `engines.toml` field semantics, overrides, and hand-editing, defer to the
`configure-engines-toml` skill and its
[engines-toml-schema.md](../configure-engines-toml/references/engines-toml-schema.md).

The human-readable runbook is [install.md](../../../../docs/install.md) in the
repo docs tree (or the copy beside the installed package docs).

## Prerequisites

Confirm with the user:

1. **Python 3.12** — required for the public Isaac pip package; the venv must use 3.12.
2. **Git** — only if the wizard will clone `simready_foundations` (HTTPS or SSH to `gitlab-master.nvidia.com`).
3. **Disk** — about 30 GB free if pip-installing Isaac; less if pointing at an existing standalone install.
4. **Engine** — Kit or Isaac Sim: either an existing launcher (`isaac-sim.bat` / `isaac-sim.sh`) or willingness to pip-install Isaac into the venv.

## 1. Workspace and virtual environment

Ask where the workspace should live. Defaults:

| OS | Default workspace | Create venv | Activate |
|---|---|---|---|
| Windows | `C:\simready_testing` | `python -m venv .venv` | `.\.venv\Scripts\Activate.ps1` or `activate.bat` |
| Linux (Ubuntu) | `~/simready_testing` | `python3.12 -m venv .venv` | `source .venv/bin/activate` |

**Linux only:** if venv creation fails with *ensurepip is not available*, install `python3.12-venv` via `apt` or use `python3.12 -m venv --without-pip .venv` and bootstrap pip with `get-pip.py`.

Then upgrade pip: `python -m pip install --upgrade pip`.

## 2. Install the framework

**Published wheels (default):**

```bash
pip install "simready-benchmark[kit]"
```

The `[kit]` extra installs `simready-benchmark-engine-kit` plus `usd-core`, `numpy`, and `Pillow`.

**Develop from source (simready-explorer tree):** editable install of both packages:

```bash
pip install -e ./packages/simready_benchmark -e ./packages/simready_benchmark_engine_kit
```

(run from `source/libraries/simready-benchmark`; each package needs a local `pyproject.toml` shim.)

Verify:

| OS | Locate CLI | Version |
|---|---|---|
| Windows | `where simready-benchmark` | `simready-benchmark --version` |
| Linux | `which simready-benchmark` | `simready-benchmark --version` |

## 3. Run the setup wizard

```bash
simready-benchmark --init-engines-toml
```

The wizard acquires `simready_foundations` (clone or existing), detects or installs Isaac, and writes `~/.simready-benchmark/engines.toml` with `project_config` and `output_dir`.

**Unattended / existing assets** — use flags so nothing prompts:

| Flag | Use when |
|---|---|
| `--foundations-path <DIR>` | User already has a foundations clone |
| `--no-clone-foundations` | Refuse to clone |
| `--executable-path <PATH>` | Standalone Isaac: `isaac-sim.sh` (Linux) or `isaac-sim.bat` (Windows) |
| `--no-install-isaac` | Refuse pip Isaac download |
| `--install-isaac` | Force pip install when none detected |
| `--no-overwrite` | Keep existing `engines.toml` |

Example (Linux, existing clone + standalone Isaac):

```bash
simready-benchmark --init-engines-toml \
  --foundations-path /path/to/simready_foundations --no-clone-foundations \
  --executable-path /path/to/isaac_sim/isaac-sim.sh --no-install-isaac
```

**Standalone Isaac version:** the wizard only reads the pip `isaacsim` package version. If `version` is missing in `engines.toml`, add `version = "5.1.0"` (major version from the install `VERSION` file) under `[kit.isaac_sim]`.

## 4. Verify configuration

```bash
simready-benchmark --show-config
```

Confirm:

- `engines.toml` loaded from the expected path (`[ok]` on `executable_path`).
- `project_config` and `sr_specs` resolve with `[ok]`.
- `output_dir` points at `_testing` under the foundations clone.

## 5. First test run

```bash
simready-benchmark --list-tests
simready-benchmark --assets <foundations>/sample_content/common_assets/props_general/apple_a01
```

Exit code `0` means a clean pass. Results land under `<foundations>/_testing/`.

## 6. Day-to-day reminder

The venv is per-shell. Reactivate before every session:

| OS | Commands |
|---|---|
| Windows | `cd C:\simready_testing` then `.\.venv\Scripts\activate` |
| Linux | `cd ~/simready_testing` then `source .venv/bin/activate` |

Refresh with `simready-benchmark --update` (foundations git pull, optional Isaac upgrade, framework upgrade hint).

## Windows / Linux quick reference

| Topic | Windows | Linux (Ubuntu) |
|---|---|---|
| Python install | python.org 3.12 installer, Add to PATH | `apt install python3.12 python3.12-venv` |
| Long paths | Disable 260-char limit in installer | Not applicable |
| Venv activate | `.venv\Scripts\activate` | `source .venv/bin/activate` |
| Find CLI | `where simready-benchmark` | `which simready-benchmark` |
| Isaac launcher | `isaac-sim.bat` | `isaac-sim.sh` |
| PowerShell scripts blocked | `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` | Not applicable |
| Venv ensurepip error | Rare | `apt install python3.12-venv` or `get-pip.py` bootstrap |

## Key rules

- Always use Python **3.12** for the venv when pip-installing Isaac.
- Always activate the venv before `simready-benchmark` commands.
- Prefer the wizard over hand-writing `engines.toml` for first-time setup.
- Use `--foundations-path` and `--executable-path` when the user already has clones or a standalone Isaac tree.
- After setup, use `configure-engines-toml` only for repairs, second engines, or NVCF — not for repeating full install.
