Installation

Installation#

EmbodiChain is a Python framework built on the DexSim 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.

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

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+ recommended)

GPU

NVIDIA GPU with compute capability 7.0+

NVIDIA driver

≥ 535 (tested on driver branches up to 595.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

Core: 3.10, 3.11, or 3.12; gensim / bpy: 3.11

Display (optional)

X11 DISPLAY for interactive viewer windows

[!IMPORTANT] Python 3.12 is supported for the core EmbodiChain installation. The optional gensim extra includes Blender’s ABI-specific bpy package and must run in a Python 3.11 environment. If your core installation uses Python 3.12, create a separate Python 3.11 environment for gensim and start its commands from that environment; there is no automatic cross-environment handoff.

NVIDIA drivers are backward compatible with applications built against older CUDA toolkits. A 595-series host driver therefore works with the current CUDA 12.8 Docker image and wheels; installing a CUDA 13 toolkit on the host is not required. See NVIDIA’s CUDA compatibility documentation for details.

[!NOTE] 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.

Package indexes#

EmbodiChain and its simulation backend are published on a DexForce package index. Generative-simulation extras also need Blender’s index for the bpy wheel.

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

Reuse these flags on every pip / uv pip install command:

DEXFORCE_INDEX="http://pyp.open3dv.site:2345/simple/"
DEXFORCE_TRUSTED_HOST="pyp.open3dv.site"
BLENDER_INDEX="https://download.blender.org/pypi/"

PIP_EXTRA_ARGS="--extra-index-url ${DEXFORCE_INDEX} --trusted-host ${DEXFORCE_TRUSTED_HOST}"
GENSIM_EXTRA_ARGS="${PIP_EXTRA_ARGS} --extra-index-url ${BLENDER_INDEX}"

[!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}".

Local installation#

Use a dedicated virtual environment to avoid conflicts with system Python packages. For the core package, choose Python 3.10, 3.11, or 3.12. The examples below use Python 3.12; choose Python 3.11 instead if you plan to install gensim in the same environment.

1. Create a virtual environment#

With uv (recommended):

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python 3.12 .venv
source .venv/bin/activate

With pip:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

2. Install EmbodiChain#

Set the index variables from 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}

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:

git clone https://github.com/DexForce/EmbodiChain.git
cd EmbodiChain
uv venv --python 3.12 .venv && source .venv/bin/activate
uv pip install -e . \
  --extra-index-url http://pyp.open3dv.site:2345/simple/ \
  --trusted-host pyp.open3dv.site

Example — install from PyPI with pip:

pip install embodichain \
  --extra-index-url http://pyp.open3dv.site:2345/simple/ \
  --trusted-host pyp.open3dv.site

This pulls in dexsim_engine (Python package dexsim) and the rest of the core dependencies declared in pyproject.toml.

3. Official task environments#

The main embodichain distribution includes the official task environments as the embodichain_tasks import package, together with their JSON/YAML configs. Both a published-wheel install and pip install -e . register the embodichain.tasks entry point automatically; do not install embodichain_tasks/ separately.

If an older checkout was installed with pip install -e embodichain_tasks/, remove that legacy editable distribution once before reinstalling the main project:

pip uninstall -y embodichain_tasks
pip install -e .

Commands can continue to use repository-style paths such as embodichain_tasks/configs/tasks/manipulation/tableware/pour_water/task.cobotmagic.yaml. EmbodiChain resolves these paths from the checkout when present and otherwise from the installed wheel.

Optional: cuRobo V2 motion planning#

Install cuRobo separately to use EmbodiChain’s CUDA-accelerated, collision-aware motion planner. cuRobo is intentionally not part of the core dependency set, and its Git source requirement cannot be included in metadata published to PyPI. Select exactly one command that matches the CUDA version used by PyTorch in the active environment:

python -c "import torch; print(torch.version.cuda)"

nvidia-smi reports the newest CUDA version supported by the installed driver, which can be newer than the CUDA runtime used by PyTorch and is therefore not the value to use when choosing the cuRobo extra.

The normal EmbodiChain environment already provides PyTorch, so prefer one of the non-torch variants:

# CUDA 12.x
uv pip install \
  "nvidia-curobo[cu12] @ git+https://github.com/NVlabs/curobo.git@v0.8.0"

# CUDA 13.x
uv pip install \
  "nvidia-curobo[cu13] @ git+https://github.com/NVlabs/curobo.git@v0.8.0"

For a fresh environment that also needs cuRobo to select and install PyTorch, replace cu12 or cu13 with cu12-torch or cu13-torch. The same source requirements work with pip; replace uv pip install with pip install.

Recommended for the current CUDA 12.x EmbodiChain stack:

uv pip install \
  "nvidia-curobo[cu12] @ git+https://github.com/NVlabs/curobo.git@v0.8.0"

python -c "import curobo; print(curobo.__version__)"
pytest --pyargs curobo.tests

The dependency is installed from NVIDIA’s source repository and pinned to the cuRobo V2 v0.8.0 release. cuRobo has stricter requirements than the core EmbodiChain installation: Linux, Python 3.10–3.13, a supported NVIDIA GPU with at least 4 GB VRAM, and a driver that supports CUDA 12 or newer. See NVIDIA’s official installation guide for the current compatibility requirements, and see cuRobo V2 Planner for EmbodiChain configuration and usage. cuRobo planning always runs on CUDA, but the SimulationManager physics device may be either CPU or CUDA.

Optional: generative simulation (gensim)#

Install the gensim extra for SimReady asset pipelines, Blender-based mesh processing, and pyrender. It requires a Python 3.11 environment because its bpy wheel is ABI-specific. Use the Blender index in the install command.

If your core installation uses Python 3.12, create and activate a separate Python 3.11 environment before running any of the commands below. The current GenSim launchers use the interpreter that starts them, so start Blender-based commands from this Python 3.11 environment.

Source

Tool

Command

PyPI

uv

uv pip install "embodichain[gensim]" ${GENSIM_EXTRA_ARGS}

PyPI

pip

pip install "embodichain[gensim]" ${GENSIM_EXTRA_ARGS}

Git clone

uv

uv pip install -e ".[gensim]" ${GENSIM_EXTRA_ARGS}

Git clone

pip

pip install -e ".[gensim]" ${GENSIM_EXTRA_ARGS}

Example — separate Python 3.11 environment:

uv venv --python 3.11 .venv-gensim
source .venv-gensim/bin/activate
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/

[!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.

For SimReady pipeline usage and LLM configuration, see SimReady Asset Pipeline.

Verify installation#

Quick check (all install methods)#

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:

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

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

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

Optional GPU smoke test:

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

For a headless browser view, enable Viser:

python scripts/tutorials/sim/create_scene.py --viser

Open the endpoint printed in the terminal, normally http://127.0.0.1:8080. On a remote machine, keep the default loopback binding and forward the port:

ssh -N -L 8080:127.0.0.1:8080 user@worker-host

See Browser visualization with Viser for supported objects, camera preview, update-rate options, and remote-access guidance.

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).

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.

No module named 'curobo'

Install the CUDA-matched cuRobo source requirement separately, such as uv pip install "nvidia-curobo[cu12] @ git+https://github.com/NVlabs/curobo.git@v0.8.0".

bpy install fails

Include the Blender index (https://download.blender.org/pypi/) and use Python 3.11. bpy is not available for the core Python 3.12 environment.

Next steps#

Contents