Installation¶
Users install a wheel from PyPI; it bundles the C++ libraries and needs no compiler, no ROS and no conda. Contributors build from source with pixi.
Users: install from PyPI¶
--pre installs the current release candidate, 0.36.0.0rc1; drop it once 0.36.0.0 is final.
The wheel bundles all C++ dependencies (~30 MB). No compiler needed. It
depends on a second wheel at the same version, tesseract-robotics-nanobind-support (~40 MB):
tesseract's example robots and meshes, which the examples and these pages load. It is separate so
the bindings and the data split the download.
from tesseract_robotics import get_tesseract_resource_path
from tesseract_robotics.common import GeneralResourceLocator
from tesseract_robotics.planning import Robot
locator = GeneralResourceLocator(paths=[get_tesseract_resource_path()])
robot = Robot.from_tesseract_support("abb_irb2400", locator)
print(f"Loaded: {len(robot.get_joint_names('manipulator'))} joints")
Supported platforms:
| OS | Architectures | Minimum |
|---|---|---|
| Linux | x86_64, aarch64 | manylinux_2_39: Ubuntu 24.04, Debian 13 (Ubuntu 22.04 stays on 0.35.0.8) |
| macOS | arm64 | macOS 15.0 (macosx_15_0, imposed by the bundled libomp) |
| Windows | x86_64 |
Python versions: 3.12–3.15, from one cp312-abi3 stable-ABI wheel per platform.
That includes Rhino 9, which embeds CPython 3.13. Rhino 8 (CPython 3.9) and Python
3.10–3.11 stay on 0.35.0.8, the last release with wheels for them.
On 3.15, zstandard, which viser requires, compiles from source until it ships 3.15 wheels, so a plain uv pip install needs a C compiler there.
Developers: build from source¶
Prerequisites¶
Install pixi:
You also need the platform's C++17 compiler (Apple clang, gcc/g++ or MSVC; pixi does not
provide it), git, and disk for .native/ (5.2 GB on macOS arm64 after a build).
Build¶
git clone https://github.com/tesseract-robotics/tesseract_nanobind.git
cd tesseract_nanobind
pixi run build # native-build, then the bindings (editable) and the support data
pixi run build first runs pixi run native-build, which compiles the C++ stack (tesseract,
trajopt, tesseract_planning, descartes_light, opw_kinematics, ruckig, boost_plugin_loader on
vcpkg's third-party libraries) into .native/<triplet>/ with scripts/native_stack.py, the
script the wheel workflow runs. The first build compiles the whole stack and is slow; each of
its stages records a content-addressed identity, so later runs skip a stage whose inputs did not
change. The bindings then compile against .native/<triplet>/ws/install. See
The native stack for the stages and how to change them.
Run an example:
What pixi does¶
Pixi resolves the toolchain and the Python environment from one lockfile. It does not provide
the C++ stack, which scripts/native_stack.py builds:
| Category | Examples |
|---|---|
| Build tools | cmake, ninja, make, pkg-config, ccache, colcon, vcs2l |
| Python packages | numpy, scipy, nanobind, scikit-build-core, pytest, loguru |
| Platform-specific | llvm-openmp (macOS) |
The pixi.lock file pins the exact versions of the toolchain and Python packages, so every
developer and CI machine builds the bindings with the same tools. The C++ stack is pinned
elsewhere: the commits in dependencies.rosinstall, and the vcpkg revision and package list in
scripts/native_stack.toml.
C++ dependencies¶
scripts/native_stack.py builds three stages into .native/<triplet>/:
| Stage | Source | Output |
|---|---|---|
sources |
vcs import of dependencies.rosinstall (tesseract, trajopt, tesseract_planning, descartes_light, opw_kinematics, ruckig, boost_plugin_loader) |
ws/src |
vcpkg |
the revision and packages in scripts/native_stack.toml (Eigen, Boost, OMPL, FCL, Bullet, PCL, spdlog, ...) |
vcpkg/installed/<triplet> |
colcon |
the sources against the vcpkg libraries | ws/install (TESSERACT_CPP_PREFIX) |
To run any command against that stack, use python scripts/native_stack.py exec -- <command>.
Both the pixi tasks and the wheel workflow go through the same script, so a development build and
a wheel compile the same sources with the same flags.
Submodule (optional)¶
The ws/src/tesseract_ros_workcell submodule provides industrial workcell models:
It fetches about 50 MB of URDF/mesh assets for a multi-robot workcell with
positioner and rail, used by src/tesseract_robotics/examples/twc_workcell_positioner_viewer.py.
Name the path: a bare git submodule update --init also clones the upstream/
sources, which only the 0.36 inner loop needs.
Troubleshooting¶
Plugin loading errors¶
Run within pixi: pixi run python your_script.py or enter pixi shell first.
OpenMP crashes (macOS)¶
Pixi installs llvm-openmp from conda-forge. If you have Homebrew's libomp installed, library conflicts can cause crashes. The pixi environment isolates this, but running outside pixi shell may pick up the wrong library.
The PyPI wheels carry their own libomp.dylib. Up to 0.35.0.8, inside a conda or pixi environment that has llvm-openmp that made two runtimes: Descartes aborts with OMP: Error #15, and under KMP_DUPLICATE_LIB_OK=TRUE it survives num_threads=1 but segfaults at 2; install those wheels into a venv, or use the pixi environment's editable install. From 0.36.0.0rc1 the wheel looks for libomp.dylib in the environment's lib/ first and loads its bundled copy only when the environment has none, so the process gets one runtime either way. The mechanism is in macOS Wheel Gotchas.
Scattered segfaults / "double free or corruption"¶
Random crashes across kinematics, planning, and trajopt code paths, while imports and simple
geometry work, are the signature of bindings compiled against a different C++ stack than the one
they load. Rebuild both against the same inputs: pixi run build recompiles any stage whose
inputs changed, and an editable install keeps pointing at .native/<triplet>/ws/install.