Skip to content

Improve installation guide and deduplicate gensim install docs #293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yuecideng merged 2 commits into from
Jun 4, 2026
Merged

Improve installation guide and deduplicate gensim install docs #293

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e5fc958
docs(quick_start): restructure installation guide
yuecideng Jun 4, 2026
0da022d
wip
yuecideng Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 2 additions & 42 deletions docs/source/features/generative_sim/simready_pipeline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,49 +23,9 @@ python -m embodichain preview-asset \

## Prerequisites

The full pipeline uses Blender, trimesh, pyrender, and an OpenAI-compatible multimodal chat completions endpoint. Install EmbodiChain with the `gensim` extra and enable both the EmbodiChain package index and Blender package index.
The full pipeline uses Blender, trimesh, pyrender, and an OpenAI-compatible multimodal chat completions endpoint. Install EmbodiChain with the `gensim` extra first — see [Installation (gensim extra)](../../quick_start/install.md#optional-generative-simulation-gensim) for package indexes and install commands.

Install from PyPI with `uv`:

```bash
uv pip install "embodichain[gensim]" \
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site \
--extra-index-url https://download.blender.org/pypi/
```

Install from source with `uv`:

```bash
git clone https://github.com/DexForce/EmbodiChain.git
cd EmbodiChain
uv pip install -e ".[gensim]" \
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site \
--extra-index-url https://download.blender.org/pypi/
```

Install from PyPI with `pip`:

```bash
pip install "embodichain[gensim]" \
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site \
--extra-index-url https://download.blender.org/pypi/
```

Install from source with `pip`:

```bash
git clone https://github.com/DexForce/EmbodiChain.git
cd EmbodiChain
pip install -e ".[gensim]" \
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site \
--extra-index-url https://download.blender.org/pypi/
```

Set the OpenAI-compatible LLM api(OpenAI, Gemini, Doubao, etc.) before running the pipeline, or configure them in `embodichain/gen_sim/simready_pipeline/configs/gen_config.json`. Environment variables override the JSON config.
Set the OpenAI-compatible LLM API (OpenAI, Gemini, Doubao, etc.) before running the pipeline, or configure them in `embodichain/gen_sim/simready_pipeline/configs/gen_config.json`. Environment variables override the JSON config.

OpenAI-compatible API example:

Expand Down
224 changes: 158 additions & 66 deletions docs/source/quick_start/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,136 +1,228 @@
# Installation

## System Requirements
EmbodiChain is a Python framework built on the [DexSim](https://github.com/DexForce) simulation engine (`dexsim_engine` on PyPI). This guide covers system requirements, package indexes, Docker and local install paths, optional generative-simulation dependencies, and verification.

After installation, continue with the [Quick Start Tutorial](../tutorial/index.rst).

## Choose your setup

| Path | Best for | Notes |
|------|----------|-------|
| **Docker** | First run, reproducible GPU sim | Pre-built image with CUDA 12.8, Vulkan, and Python 3.11 |
| **Local + [uv](https://github.com/astral-sh/uv)** | Day-to-day development | Fast installs; recommended with a virtual environment |
| **Local + pip** | Simple environments | Use a virtual environment |

## System requirements

| Component | Requirement |
|-----------|------------|
| **OS** | Linux (x86_64): Ubuntu 20.04+ |
| **GPU** | NVIDIA with compute capability 7.0+ |
| **NVIDIA Driver** | 535 - 570 (580+ is untested and may be unstable) |
|-----------|-------------|
| **OS** | Linux x86_64 (Ubuntu 20.04+ recommended) |
| **GPU** | NVIDIA GPU with compute capability 7.0+ |
| **NVIDIA driver** | ≥ 535 (tested on driver branches up to 580.x) |
| **CUDA** | 12.x (aligned with the Docker image and `dexsim_engine` wheels) |
| **Vulkan** | Host ICD/layer files for GPU rendering (see Docker notes) |
| **Python** | 3.10 or 3.11 |
| **Display** (optional) | X11 `DISPLAY` for interactive viewer windows |

> [!NOTE]
> Ensure your NVIDIA driver is compatible with your chosen PyTorch wheel. We recommend installing PyTorch from the [official PyTorch instructions](https://pytorch.org/get-started/locally/) for your CUDA version.
> **PyTorch:** EmbodiChain depends on PyTorch transitively (for example via `dexsim_engine` and `pytorch_kinematics`). If you install or upgrade PyTorch separately, match the wheel to your CUDA version using the [official PyTorch install selector](https://pytorch.org/get-started/locally/).

## Installation
## Package indexes

### Docker (Recommended)
EmbodiChain and its simulation backend are published on a DexForce package index. Generative-simulation extras also need Blender's index for the `bpy` wheel.

We strongly recommend using our pre-configured Docker environment, which contains all necessary dependencies including CUDA, Vulkan, and GPU rendering support.
| Index | URL | Used for |
|-------|-----|----------|
| **DexForce (required)** | `http://pyp.open3dv.site:2345/simple/` | `embodichain`, `dexsim_engine`, and related wheels |
| **Blender (gensim only)** | `https://download.blender.org/pypi/` | `bpy` |

**1. Pull the image:**
Reuse these flags on every `pip` / `uv pip` install command:

```bash
docker pull dexforce/embodichain:ubuntu22.04-cuda12.8
```
DEXFORCE_INDEX="http://pyp.open3dv.site:2345/simple/"
DEXFORCE_TRUSTED_HOST="pyp.open3dv.site"
BLENDER_INDEX="https://download.blender.org/pypi/"

**2. Start a container:**
PIP_EXTRA_ARGS="--extra-index-url ${DEXFORCE_INDEX} --trusted-host ${DEXFORCE_TRUSTED_HOST}"
GENSIM_EXTRA_ARGS="${PIP_EXTRA_ARGS} --extra-index-url ${BLENDER_INDEX}"
```

Use the provided run script ([`docker/docker_run.sh`](../../../docker/docker_run.sh)), which handles GPU driver and Vulkan mounting:
> [!TIP]
> To avoid repeating flags, you can configure pip once:
> `pip config set global.extra-index-url "${DEXFORCE_INDEX}"` and
> `pip config set global.trusted-host "${DEXFORCE_TRUSTED_HOST}"`.
Comment on lines +50 to +53

```bash
./docker/docker_run.sh <container_name> <data_path>
```
## Docker (recommended for first run)

### uv (Recommended for local development)
The pre-configured image includes CUDA 12.8, Vulkan-related mounts, and dependencies needed for GPU simulation and rendering.

> [!TIP]
> [uv](https://github.com/astral-sh/uv) is an extremely fast Python package manager and project manager. We recommend using `uv` for local development due to its significantly faster dependency resolution and installation times compared to pip.
### Prerequisites

**Install uv:**
- [Docker](https://docs.docker.com/engine/install/) with [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
- NVIDIA driver ≥ 535 on the host
- For **GUI** runs: working X11 forwarding (`DISPLAY`, `~/.Xauthority`, `/tmp/.X11-unix`)
- For **headless** servers: no display required; use `--headless` in tutorial scripts

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Pull and start a container

**Install from PyPI:**
**1. Pull the image:**

```bash
uv pip install embodichain --extra-index-url http://pyp.open3dv.site:2345/simple/ --trusted-host pyp.open3dv.site
docker pull dexforce/embodichain:ubuntu22.04-cuda12.8
```

**Install from source (editable mode):**
**2. Start a container** using the repo script `docker/docker_run.sh` (mounts GPU drivers, Vulkan, shared memory, and your data directory):

```bash
git clone https://github.com/DexForce/EmbodiChain.git
cd EmbodiChain
uv pip install -e . --extra-index-url http://pyp.open3dv.site:2345/simple/ --trusted-host pyp.open3dv.site
./docker/docker_run.sh <container_name> <data_path>
```

### pip (PyPI)
| Argument | Meaning |
|----------|---------|
| `container_name` | Name for the new container |
| `data_path` | Host directory mounted at `/root/workspace` inside the container |

> [!TIP]
> We strongly recommend using a virtual environment to avoid dependency conflicts.
The script checks for Vulkan ICD/layer and EGL vendor JSON files on the host. Warnings usually mean reduced rendering support; the script exits only when required driver paths are missing entirely.

**3. Attach to the running container:**

```bash
pip install embodichain --extra-index-url http://pyp.open3dv.site:2345/simple/ --trusted-host pyp.open3dv.site
docker exec -it <container_name> bash
```

### From Source
Inside the container, install or update EmbodiChain with the [local installation](#local-installation) commands if needed, then [verify](#verify-installation).

> [!TIP]
> We strongly recommend using a virtual environment to avoid dependency conflicts.
> [!NOTE]
> The script uses `--network=host`, `--gpus all`, and a large `--shm-size` for simulation workloads. Adjust mounts in `docker/docker_run.sh` if your driver files live under `/etc` instead of `/usr/share`.

```bash
git clone https://github.com/DexForce/EmbodiChain.git
cd EmbodiChain
pip install -e . --extra-index-url http://pyp.open3dv.site:2345/simple/ --trusted-host pyp.open3dv.site
```
## Local installation

### Generative Simulation Dependencies
Use a dedicated virtual environment to avoid conflicts with system Python packages.

If you want to use the generative simulation features, install EmbodiChain with the `gensim` extra. This installs the additional rendering and asset-processing dependencies, including `pyrender` and `bpy`. The `bpy` wheel is distributed from Blender's package index, so the Blender index must be included in the install command.
### 1. Create a virtual environment

**Install from PyPI with `uv`:**
**With uv (recommended):**

```bash
uv pip install "embodichain[gensim]" \
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site \
--extra-index-url https://download.blender.org/pypi/
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python 3.11 .venv
source .venv/bin/activate
```

**Install from source with `uv`:**
**With pip:**

```bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

### 2. Install EmbodiChain

Set the index variables from [Package indexes](#package-indexes), then pick one row:

| Source | Tool | Command |
|--------|------|---------|
| PyPI | uv | `uv pip install embodichain ${PIP_EXTRA_ARGS}` |
| PyPI | pip | `pip install embodichain ${PIP_EXTRA_ARGS}` |
Comment on lines +128 to +129
| Git clone | uv | `uv pip install -e . ${PIP_EXTRA_ARGS}` |
| Git clone | pip | `pip install -e . ${PIP_EXTRA_ARGS}` |

**Example — editable install from source with uv:**

```bash
git clone https://github.com/DexForce/EmbodiChain.git
cd EmbodiChain
uv pip install -e ".[gensim]" \
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site \
--extra-index-url https://download.blender.org/pypi/
uv venv --python 3.11 .venv && source .venv/bin/activate
uv pip install -e . \
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site
```

**Install from PyPI with `pip`:**
**Example — install from PyPI with pip:**

```bash
pip install "embodichain[gensim]" \
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site \
--extra-index-url https://download.blender.org/pypi/
pip install embodichain \
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site
```

**Install from source with `pip`:**
This pulls in `dexsim_engine` (Python package `dexsim`) and the rest of the core dependencies declared in `pyproject.toml`.

## Optional: generative simulation (`gensim`)

Install the `gensim` extra for SimReady asset pipelines, Blender-based mesh processing, and `pyrender`. The `bpy` wheel is hosted on Blender's index and must be included in the install command.

| Source | Tool | Command |
|--------|------|---------|
| PyPI | uv | `uv pip install "embodichain[gensim]" ${GENSIM_EXTRA_ARGS}` |
| PyPI | pip | `pip install "embodichain[gensim]" ${GENSIM_EXTRA_ARGS}` |
Comment on lines +160 to +161
| Git clone | uv | `uv pip install -e ".[gensim]" ${GENSIM_EXTRA_ARGS}` |
| Git clone | pip | `pip install -e ".[gensim]" ${GENSIM_EXTRA_ARGS}` |

**Example:**

```bash
git clone https://github.com/DexForce/EmbodiChain.git
cd EmbodiChain
pip install -e ".[gensim]" \
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site \
--extra-index-url https://download.blender.org/pypi/
--extra-index-url http://pyp.open3dv.site:2345/simple/ \
--trusted-host pyp.open3dv.site \
--extra-index-url https://download.blender.org/pypi/
```

## Verify Installation
> [!TIP]
> When using **uv** from a source checkout, `pyproject.toml` already defines the Blender index under `[tool.uv.index]` for the `bpy` source. You still need the DexForce index flags for `dexsim_engine`.

Run the demo script to confirm everything is set up correctly:
For SimReady pipeline usage and LLM configuration, see [SimReady Asset Pipeline](../features/generative_sim/simready_pipeline.md).

## Verify installation

### Quick check (all install methods)

```bash
python -c "import embodichain, dexsim; print('embodichain', embodichain.__version__); print('dexsim', dexsim.__version__)"
```

You should see version strings for both packages with no import errors.

### Simulation tutorial (source tree or Docker with repo)

The tutorial script `scripts/tutorials/sim/create_scene.py` ships with the repository. Run it from the **repository root**:

```bash
cd /path/to/EmbodiChain
python scripts/tutorials/sim/create_scene.py
```

If the installation is successful, you will see a simulation window with a rendered scene. To run without a display:
- **With a display:** omit `--headless` to open the DexSim viewer after the scene is built.
- **Headless / SSH:** use `--headless` to run without a window (FPS logs in the terminal):

```bash
python scripts/tutorials/sim/create_scene.py --headless
```

Optional GPU smoke test:

```bash
python scripts/tutorials/sim/create_scene.py --headless --device cuda
```

Press `Ctrl+C` to stop; the script cleans up the simulation on exit.

## Troubleshooting

| Symptom | What to try |
|---------|-------------|
| `Could not find a version` / `No matching distribution` for `embodichain` or `dexsim_engine` | Add the DexForce index and `--trusted-host pyp.open3dv.site` (see [Package indexes](#package-indexes)). |
| `No module named 'dexsim'` after install | Reinstall with the DexForce index; `dexsim` is provided by the `dexsim_engine` package. |
| Docker Vulkan / EGL warnings from `docker_run.sh` | Install host NVIDIA drivers and Vulkan user-space packages; paths must be files under `/etc` or `/usr/share`, not directories. |
| Viewer does not open | Export `DISPLAY`, allow X11 access (`xhost +local:` on the host), and ensure `~/.Xauthority` is mounted (the run script does this by default). |
| PyTorch / CUDA errors at runtime | Reinstall a PyTorch build that matches your driver/CUDA from [pytorch.org](https://pytorch.org/get-started/locally/). |
| `bpy` install fails | Include the Blender index (`https://download.blender.org/pypi/`) and use Python 3.10 or 3.11. |

## Next steps

- [Quick Start Tutorial](../tutorial/index.rst)
- [Simulation Manager](../overview/sim/sim_manager.md)
- [Build documentation](docs.md)
2 changes: 1 addition & 1 deletion embodichain/lab/gym/envs/managers/manager_base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -372,7 +372,7 @@ def _process_functor_cfg_at_play(self, functor_name: str, functor_cfg: FunctorCf
* Resolving the scene entity configuration for the functor.
* Initializing the functor if it is a class.

Since the above steps rely on PhysX to parse over the simulation scene, they are deferred
Since the above steps rely on dexsim to parse over the simulation scene, they are deferred
until the simulation starts playing.

Args:
Expand Down
Loading