PyTrees

[About] [What's New?] [Documentation] [Getting Started] [Next Steps] [Maintainers] [Acknowledgments] [Releases]

About

PyTrees is a Python implementation of behaviour trees designed to facilitate the rapid development of medium sized decision making engines for use in fields like robotics.

Brief feature list:

Behaviours, Decorators, Sequences, Selectors, Parallels and BehaviourTree.
Blackboards for data sharing.
A useful library of behaviours, decorators, and idioms.
A more abstract ports API and XML parser for declarative behavior definitions.
Serialise to a dot graph or render to ascii/unicode in a terminal.
Tested on Linux and Mac (YMMV with Windows).

What's New?

[2026-06-27] Modernized project infrastructure with uv, added support for Python 3.14.
[2026-05-19] Typed input/output ports for behaviours, with XML parser support.
[2025-11-13] New ForEach decorator.
[2025-11-13] New CompareBlackboardVariables behaviour, with comparison expressions that allow callables.
[2025-01-11] Support for Python 3.12 was added, and Python 3.8 was dropped.

Documentation

Getting Started

Released versions of PyTrees can be installed directly from:

PyPi: pip install py_trees
conda-forge: conda install conda-forge::py-trees

Alternatively, you can clone the repo, install uv, and you're up and running in under 5 minutes:

# Install dependencies into a .venv
$ uv sync

# Explore the demos
$ uv run py-trees-demo-<tab>-<tab>
py-trees-demo-action-behaviour            py-trees-demo-context-switching           py-trees-demo-logging
py-trees-demo-behaviour-lifecycle         py-trees-demo-display-modes               py-trees-demo-pick-up-where-you-left-off
py-trees-demo-blackboard                  py-trees-demo-dot-graphs                  py-trees-demo-selector
py-trees-demo-blackboard-namespaces       py-trees-demo-either-or                   py-trees-demo-sequence
py-trees-demo-blackboard-remappings       py-trees-demo-eternal-guard               py-trees-demo-tree-stewardship
$ uv run py-trees-demo-blackboard
...

# Hack some Code

# Run the Formatter, Linter, Type-Checker and Tests
$ uv run ruff format
$ uv run ruff check
$ uv run ty check
$ uv run pytest -s tests/

# Contribute a PR!
# https://github.com/splintered-reality/py_trees/blob/devel/CONTRIBUTING.md

See DEVELOPING.md for more detail. And be froody.

Next Steps

On PyPi:

Examples:

ReadTheDocs - PyTrees ROS Tutorials - significantly more edifying than the demos, these incrementally walk through the process of building a decision making layer for a robot. These use ROS 2 (sparsely), but merely browsing should be enlightening regardless.

Visualisation:

py_trees_js - a javascript library for building your own runtime visualisation tool

Robotics:

py_trees_ros - a tree manager and behaviours designed for use specifically with ROS 2
py_trees_ros_viewer - a Qt/ROS 2 implementation of py_trees_js

Maintainers

Daniel Stonier (@stonier)
Sebastian Castro (@sea-bass)

Acknowledgments

Contributors are welcome to add themselves here in future PRs.

Port declarations, type validation, and XML parser: contributed by Sunrise Robotics.

Releases

2.5.x - New Ports API with XML file parsing, modernized dev environment with uv, support Python 3.14.
2.4.x - New ForEach decorator, new CompareBlackboardVariables behaviour, and callables in comparison expressions.
2.3.x - Support for Python 3.12 was added, and Python 3.8 was dropped.
2.2.x - Selectors, Sequences with and without memory. Improved testing and style/type checking.
2.1.x - Chooser deprecated. API housekeeping.
2.0.x - Blackboards V2!
1.2.x - Trees can now shutdown cleanly. StatusToBlackboard and EternalGuard, Visitors get finalise().
1.1.x - Fixes for setup, tick-tock, viz.
1.0.x - Behaviours, Decorators, Composites, Blackboards, Tree Management and Viz tools.
0.y.x - First open source pre-releases.