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

1. Create a virtual environment#

With uv (recommended):

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

With pip:

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, 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.11 .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.

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}

Git clone

uv

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

Git clone

pip

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

Example:

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

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.

bpy install fails

Include the Blender index (https://download.blender.org/pypi/) and use Python 3.10 or 3.11.

Next steps#

Contents