Tesseract Python (nanobind)

Note: This is a friendly fork of tesseract_python that replaces SWIG bindings with modern nanobind bindings.

Python bindings for Tesseract robotics motion planning using nanobind.

Documentation

Maintained in /docs and published to https://tesseract-robotics.github.io/tesseract_nanobind/

Features

• Scene loading and management (URDF, SRDF, meshes)
• Collision checking (Bullet, FCL)
• Kinematics (KDL, OPW, UR)
• Motion planning (OMPL, Descartes, TrajOpt)
• Time parameterization (TOTG, ISP, Ruckig)
• Task composition and pipelines
• Pythonic high-level API

for an excellent overview of Tesseract's architecture & features see this presentation on Vimeo

Installation

pip install tesseract-robotics-nanobind

Platform support:

• linux
  • x86_64 - 3.10-3.14
  • aarch64 - 3.12-3.14
• windows
  • x86_64 - 3.9-3.14
• macOS
  • arm64 - 3.9-3.14

Quick Start

from tesseract_robotics.planning import (
    Robot, MotionProgram, JointTarget, CartesianTarget,
    Pose, box, create_obstacle, TaskComposer,
)

# Load robot
robot = Robot.from_urdf(
    "package://tesseract_support/urdf/abb_irb2400.urdf",
    "package://tesseract_support/urdf/abb_irb2400.srdf"
)

# Add obstacle
create_obstacle(robot, "box", box(0.5, 0.5, 0.5), Pose.from_xyz(0.5, 0, 0.3))

# Build motion program
program = (MotionProgram("manipulator", tcp_frame="tool0")
    .set_joint_names(robot.get_joint_names("manipulator"))
    .move_to(JointTarget([0, 0, 0, 0, 0, 0]))
    .move_to(CartesianTarget(Pose.from_xyz(0.5, 0.3, 0.8)))
)

# Plan
composer = TaskComposer.from_config()
result = composer.plan(robot, program)

if result.successful:
    for pt in result.trajectory:
        print(pt.positions)

Low-Level API

For direct C++ API access:

from tesseract_robotics.tesseract_environment import Environment
from tesseract_robotics.tesseract_common import GeneralResourceLocator

env = Environment()
locator = GeneralResourceLocator()
env.init("/path/to/robot.urdf", "/path/to/robot.srdf", locator)

print(f"Joints: {env.getJointNames()}")
print(f"Links: {env.getLinkNames()}")

Examples

examples are located at src/tesseract_robotics/examples.

• basic_cartesian_example.py - Simple Cartesian planning
• freespace_ompl_example.py - OMPL freespace planning
• pick_and_place_example.py - Pick and place with TrajOpt
• puzzle_piece_example.py - Cartesian path following
• And more...

Versioning

Version follows 0.A.B.C where A.B tracks the upstream Tesseract release and C is the nanobind patch number. For example, 0.34.1.0 wraps Tesseract 0.34.1.

See CHANGELOG.md for release notes.

Development

This project uses pixi exclusively for dependency management and task running — no pip, conda, or venv needed. Pixi manages the build toolchain (cmake, ninja, nanobind), the prebuilt tesseract C++ libraries (from the tesseract-robotics conda channel), and Python deps in a single lockfile.

Prerequisites

Install pixi (docs):

curl -fsSL https://pixi.sh/install.sh | bash

First-time setup

git clone --recurse-submodules https://github.com/tesseract-robotics/tesseract_nanobind.git
cd tesseract_nanobind
pixi run build    # installs prebuilt C++ libs + builds/installs bindings (editable)

pixi run build resolves the pixi env (which pulls the prebuilt tesseract C++ libs from the tesseract-robotics conda channel) and runs install (editable pip install of the Python package). Only the nanobind extensions compile locally — no more from-source C++ build.

Available tasks

Task	Description
pixi run build	Install C++ libs (conda) + build/install bindings
pixi run install	Editable install of the bindings
pixi run test	Run pytest with xdist parallelism
pixi run lint	Lint with ruff
pixi run fmt	Format with ruff
pixi run typecheck	Type check with pyright
pixi run docs	Live docs server (localhost:8000)
pixi run docs-build	Build static docs to site/

Running tests

pixi run test                              # full suite, parallel
pixi shell && pytest tests -x --testmon    # incremental (only changed)

Pre-commit hooks

pixi shell
pre-commit install
pre-commit install --hook-type pre-push

This runs ruff + auto-staging on commit, and pyright + pytest on push (configured in .pre-commit-config.yaml).

Project layout

├── pyproject.toml            # package config + pixi workspace
├── CMakeLists.txt            # nanobind build
├── src/tesseract_robotics/   # Python package + C++ extension modules
├── tests/                    # pytest suite
├── examples/                 # usage examples
├── scripts/                  # build scripts (build_{linux,macos}_wheel.sh)
└── docs/                     # mkdocs-material documentation

Building portable wheels

Editable installs bake absolute paths — not portable. For distributable wheels:

pixi run build-wheel                  # bundles native deps (Linux: patchelf, macOS: delocate)
pip install wheelhouse/tesseract*.whl

Acknowledgments

This project builds upon the excellent work of John Wason and the Tesseract Robotics team. The original tesseract_python SWIG bindings laid the foundation for this nanobind implementation.

Special thanks to:

• John Wason (Wason Technology, LLC) - Original tesseract_python author and Tesseract maintainer
• Levi Armstrong - Tesseract core developer
• Jelle Feringa (Terrestrial) - nanobind port developer
• Joel Kang (Tekton Dynamics)
• The ROS-Industrial consortium for supporting Tesseract development

License

Apache 2.0