Skip to content

Install

trusty-sim ships as prebuilt wheels. There is nothing to compile.

Platform Python Package
macOS 11+ (Apple silicon) 3.11, 3.12, 3.13 trusty-sim
Linux x86_64, glibc 2.28+ (Ubuntu 20.04+, Debian 10+, RHEL 8+) 3.11, 3.12 trusty-sim
Linux x86_64 with an NVIDIA GPU, glibc 2.28+ 3.12 trusty-sim-cuda12, see GPU Installation

On Linux, trusty-sim is the CPU build. Intel Macs, Windows and Linux on ARM are not supported yet.

Pre-release

0.1.0a5 is a pre-release while the API settles.

Make an environment and install trusty-sim, plus polyscope for the interactive viewer used in the examples:

python -m venv .venv && source .venv/bin/activate
pip install trusty-sim polyscope

If you don't have uv yet, install it first:

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

Then make an environment and install trusty-sim, plus polyscope for the interactive viewer used in the examples:

uv venv && source .venv/bin/activate
uv pip install trusty-sim polyscope

GPU Installation

For the CUDA backend, install trusty-sim-cuda12 in place of trusty-sim. It is the same library with the GPU backend built in, so it replaces trusty-sim: install one of the two in an environment, not both. If you already installed trusty-sim, run pip uninstall trusty-sim first.

You need an NVIDIA GPU and a driver that supports CUDA 12.9 (version 575 or newer). You don't need to install the CUDA toolkit: the CUDA libraries come from NVIDIA's own wheels on PyPI.

The wheel contains GPU code for these architectures, so a GPU of another one cannot run it:

Architecture GPUs
7.0 V100
7.5 T4, RTX 20 series
8.0 A100
8.6 RTX 30 series, A10
8.9 RTX 40 series, L4, L40
9.0 H100, H200
10.0 B100, B200
12.0 RTX 50 series 
python -m venv .venv && source .venv/bin/activate
pip install trusty-sim-cuda12 polyscope

uv venv && source .venv/bin/activate
uv pip install trusty-sim-cuda12 polyscope

pip installs the NVIDIA libraries the wheel depends on from PyPI.

Check that the GPU backend is there, then ask for it by name:

import trusty
print("cuda" in trusty.capabilities())
world = trusty.World(backend="cuda")

The wheel is about 52 MB, and about 200 MB once installed, because it carries GPU code for eight architectures.

Check what your build includes

import trusty
print(trusty.library_version())
print(sorted(trusty.capabilities()))

The set holds one name per module, plus accelerate or cuda when the build has that backend. Each module page lists the capability it needs. Call trusty.check_capabilities("shells") at the top of a script to fail early with a clear message.

Run the examples

Every example on these pages is a script in the trusty-docs repository. Clone it:

git clone https://github.com/tytrusty/trusty-docs
cd trusty-docs

With the environment from above active, add the packages the examples use, then run any of them with python from the repository root:

pip install trimesh matplotlib scipy
python examples/quickstart.py

Run any example with uv run from the repository root, in place of the python the other pages show. (uv run installs the CPU build; for the GPU build, use the pip route above.)

uv run examples/quickstart.py

The first uv run makes an environment in the repository with trusty-sim, the polyscope viewer and everything else the examples use; later runs reuse it.

Most examples also run headless with --no-viewer, and each script's docstring lists its options.