Set up Tesseract for motion planning and collision checking in your robotics application.
What is Tesseract?
Tesseract is a modern motion planning and collision detection framework designed for industrial robotics. It provides tools for:
- Motion planning – Find collision-free paths for robot arms, mobile bases, and complex mechanisms
- Collision detection – Check for collisions and compute distances with high accuracy
- Environment representation – Load and manage robot descriptions (URDF) and semantic information (SRDF)
- Optimization – Integrate custom planners and optimize trajectories for quality, smoothness, and constraints
The core Tesseract libraries are ROS-agnostic — they work standalone in C++ or Python applications. Optional ROS/ROS2 bindings are available if you need ROS integration.
Choose Your Path
Depending on your needs, follow the appropriate path:
Path 1: Just Want to Use Tesseract in C++ or Python?
- Skip ROS installation (optional)
- Install build tools (CMake, colcon or catkin)
- Clone and build Tesseract and dependencies
- Jump to Building Your Workspace
Path 2: Want Full ROS/ROS2 Integration?
- Install ROS or ROS 2
- Install workspace tools (catkin, catkin_tools, or colcon)
- Clone Tesseract repositories and dependencies
- Build with catkin or colcon
- Full ROS integration available after building
Path 3: Have Limited Time? Just Want to Learn?
Before You Start
System Requirements:**
Before installing Tesseract and dependencies, ensure you have the latest packages:
sudo apt-get update
sudo apt-get dist-upgrade
Installing ROS (Optional)
Tesseract core is ROS-agnostic and works perfectly without ROS. Only install ROS if:
Follow the official ROS Noetic installation guide.
ROS 2 (Recommended for new projects):**
Follow the official ROS 2 Humble or Jazzy installation guide.
- Note
- If you skip ROS, you can still use Tesseract fully. You just won't have ROS-specific packages like
tesseract_ros.
Installing Build Tools
You need tools to build Tesseract. Choose one set based on your preference:
Option A: CMake + Ninja (Minimal, Recommended)
If you just want to build the core libraries:
sudo apt-get install cmake ninja-build build-essential git
Option B: Catkin + Catkin Tools (ROS Integration)
Use this if you have ROS 1 installed:
sudo apt-get install ros-noetic-catkin python3-catkin-tools
Option C: Colcon (ROS 2 Standard)
Use this if you have ROS 2 installed:
sudo apt-get install python3-colcon-common-extensions
Optional: System Dependency Manager (Recommended)
ROSDep auto-installs system dependencies from package.xml files:
sudo apt-get install python3-rosdep
sudo rosdep init
rosdep update
If you skip ROSDep, you'll need to manually install dependencies with apt-get.
Optional: Workspace Initialization Tool
WSTool helps clone dependency repositories:
sudo apt-get install python3-wstool
Creating a Workspace
Create a workspace directory to hold Tesseract and dependencies:
mkdir -p ~/tesseract_ws/src
cd ~/tesseract_ws/src
Choose a different path if you prefer; just remember it for later commands.
Cloning Tesseract Repositories
Step 1: Clone Core Tesseract
git clone https://github.com/tesseract-robotics/tesseract.git
Step 2: Clone Planning and Additional Tools
git clone https://github.com/tesseract-robotics/tesseract_planning.git
git clone https://github.com/tesseract-robotics/tesseract_qt.git
Step 3 (ROS Only): Clone ROS Integration
If you have ROS 1 installed:
git clone https://github.com/tesseract-robotics/tesseract_ros.git
If you have ROS 2 installed:
git clone https://github.com/tesseract-robotics/tesseract_ros2.git
Installing Dependencies
Automatic Installation (Recommended if you have ROSDep)
cd ~/tesseract_ws
rosdep install -y --from-paths src --ignore-src --rosdistro noetic
Replace noetic with your ROS distribution (humble, jazzy, etc. for ROS 2).
Use WSTool to Clone Source Dependencies
If you prefer to build dependencies from source:
wstool init ~/tesseract_ws/src ~/tesseract_ws/src/tesseract_planning/dependencies.rosinstall
Manual Installation (if you don't have ROSDep)
Install key dependencies manually:
sudo apt-get install libeigen3-dev libboost-all-dev octomap-tools liboctomap-dev
- Note
- Missing dependencies will show up as CMake errors during the build. If this happens, install the missing packages and try building again.
Building Your Workspace
If using CMake + Ninja (minimal setup)
cd ~/tesseract_ws
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel $(nproc)
If using Catkin (ROS 1 users)
cd ~/tesseract_ws
source /opt/ros/noetic/setup.bash
catkin build
source devel/setup.bash
If using Colcon (ROS 2 users)
cd ~/tesseract_ws
source /opt/ros/humble/setup.bash # or jazzy, etc.
colcon build
source install/setup.bash
Build Flags (Optional)
To enable additional features during build:
# Enable testing and clang-tidy (when using colcon)
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release -DTESSERACT_ENABLE_TESTING=ON -DTESSERACT_ENABLE_CLANG_TIDY=ON
# Or with catkin
catkin build -DCMAKE_BUILD_TYPE=Release -DTESSERACT_ENABLE_TESTING=ON
Build Time Expectation
- First build: 10-20 minutes (depends on hardware and number of dependencies downloaded)
- Subsequent builds: 1-5 minutes (incremental)
Verify Your Installation
After building, verify everything works:
Test 1: Can Python find Tesseract?
python3 -c "import tesseract; print(tesseract.__version__)"
Expected output: A version number (e.g., 0.21.0)
Test 2: Run a Simple Example
See the tesseract_examples page for complete code examples. Try loading a robot:
Troubleshooting
"CMake not found"
Install CMake:
sudo apt-get install cmake
"Missing package: tesseract/..."
You likely missed cloning a repository. Check that all three repos are in ~/tesseract_ws/src:
- tesseract (core)
- tesseract_planning (motion planning)
- tesseract_qt (optional, visualization)
"[package] not found" during build
Install missing dependencies:
rosdep install -y --from-paths ~/tesseract_ws/src --ignore-src
Or manually:
sudo apt-get install lib[package]-dev
"Symbol not found" or linker errors
Try a clean rebuild:
cd ~/tesseract_ws
rm -rf build devel install # for catkin/colcon
cmake --build build --clean # for CMake
# Then rebuild
Build hangs or runs out of memory
Reduce parallel jobs:
colcon build --parallel-workers 2 # use 2 jobs instead of all cores
Or:
Python import fails after build
Ensure you sourced the setup file:
source ~/tesseract_ws/install/setup.bash # colcon
# or
source ~/tesseract_ws/devel/setup.bash # catkin
Add this to your ~/.bashrc to make it permanent:
echo "source ~/tesseract_ws/install/setup.bash" >> ~/.bashrc
Next Steps
Now that Tesseract is built, you have several paths forward:
Learn the Fundamentals
Start with these documentation pages to understand core concepts:
Work Through Examples
Study and run the provided examples in order:
- Tesseract URDF Loading Example – Load your first robot
- Tesseract SRDF Parsing Example – Add semantic information
- Tesseract Collision Checker Example – Perform collision checking
- Tesseract Scene Graph Building Example – Understand robot representation
- Tesseract Geometry Creation Example – Work with geometry types
See tesseract_examples for the complete list.
Integrate into Your Application
- For C++ projects: Link against Tesseract CMake targets
- For Python projects: Import the
tesseract module
- For ROS projects: Use tesseract_ros (ROS 1) or tesseract_ros2 (ROS 2) for node integration
Optimize and Deploy
- Profile collision checks and motion planning
- Tune solver parameters for your application
- Deploy with appropriate configuration files (URDF, SRDF, plugin configs)
Getting Help
Documentation
- tesseract_examples – Code walkthroughs
- Why Tesseract – Architecture overview
- API reference – Generated Doxygen documentation
GitHub
ROS Community
1.9.8