Skip to main content

pythonic implementation of behaviour trees

Project description

Py Trees

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


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?

  • [2023-01-28] The 2.2.x Release is out! Sequences and Selectors with AND without memory.
  • [2023-01-28] Get Started with py_trees in under 5mins.
  • [2023-01-28] This is now a poetry project with configuration governed by pyproject.toml.
    • The vestigial is only to assist distribution where PEP-517 is not yet well supported.


devel 2.2.x 2.1.x 0.7.x 0.6.x

Getting Started

You can get started on CodeSpaces (with no mismatched environment issues and in under 5mins) [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.8) (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.8) (docker) zen@py_trees:/workspaces/py_trees$ py-trees-demo-blackboard
(py-trees-py3.8) (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
py38 py310 format check mypy38 mypy310
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -e format
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -e py38
(docker) zen@py_trees:/workspaces/py_trees$ poetry run tox -e check

# Contribute a PR!

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


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


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



  • 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.2.x 2.1.x 2.0.x 1.2.x 0.7.x 0.6.x
Sources devel 2.1.x 2.1.x 2.0.x 1.2.x 0.7.x 0.6.x
Compatibility Python 3.10 Python 3.8 Python 3.10 Python 3.8 Python 3.6 Python 3.6 Python 3.6 Python 3.6 Python 2.7
CI devel-Status 2.2.x-Status - - - - -
Documentation devel-Docs 2.2.x-Docs 2.1.x-Docs 2.0.x-Docs 1.2.x-Docs 0.7.x-Docs 0.6.x-Docs


Format, Check, MyPy, Test

Check against at least one of py38 / py310 [1].

# Auto-format your code (if using VSCode, install the ufmt extension)
$ poetry run tox -e format

# Style, Format
$ poetry run tox -e check

# Type-Check
$ poetry run mypy38

# Tests
$ poetry run tox -e py38

[1] CI will test against both python versions for you, but should you wish to do so locally, open up two VSCode windows, one with the project opened in the default py38 devcontainer and the other with the py310 devcontainer.

Generate Documentation

Generate the docs, view them from ./docs/html in a browser.

# Install dependencies
$ poetry install --with docs

# Build
$ poetry run make -C docs html

On Doc dependency changes, export the requirements for ReadTheDocs

$ poetry export -f requirements.txt --with docs -o docs/requirements.txt

Publish to PyPi

If you have permission to publish on pypi:

$ poetry publish

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_trees-2.2.3.tar.gz (87.6 kB view hashes)

Uploaded Source

Built Distribution

py_trees-2.2.3-py3-none-any.whl (113.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page