py-trees 2.4.0

pythonic implementation of behaviour trees

PyTrees

[About] [What's New?] [Documentation] [Getting Started] [Next Steps] [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.
• Serialise to a dot graph or render to ascii/unicode in a terminal.
• Tested on Linux and Mac (YMMV with Windows).

What's New?

• [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

You can get started on Codespaces (with no mismatched environment issues and in under 5 minutes) [1]:

1. Fork the project to your personal account
2. Click on Code -> Codespaces -> + Create a Codespace
3. Enter the Terminal

# Install Dependencies
(docker) zen@py_trees:/workspaces/py_trees$ poetry install

# Explore the demos
(docker) zen@py_trees:/workspaces/py_trees$ poetry shell
(py-trees-py3.10) (docker) zen@py_trees:/workspaces/py_trees$ 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
(py-trees-py3.10) (docker) zen@py_trees:/workspaces/py_trees$ py-trees-demo-blackboard
...
(py-trees-py3.10) (docker) zen@py_trees:/workspaces/py_trees$ exit

# Hack some Code

# Run the Formatter, Tests, Linters and Mypy
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -l
py310 py312 format check mypy310 mypy312
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -e format
...
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -e py310
...
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -e check
...

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

[1] All of the above will, of course, work in a local environment if you have poetry installed. If you're using VSCode you don't even need that, just reopen the project in the devcontainer and be froody.

Next Steps

On PyPi:

• py_trees
• py_trees_js

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 ROS2 (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 ROS2
• py_trees_ros_viewer - a Qt/ROS2 implementation of py_trees_js

Releases

• 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.

	Devel	2.4.x	2.3.x	2.2.x	2.1.x	2.0.x
Sources
Compatibility
CI					-	-
Documentation