---
id: py-trees
version: "2.5.0"
license: BSD
license_treatment: permissive
maintenance: active
---

# py_trees — pythonic implementation of behaviour trees

License: permissive · Maintenance: active · Downloads: 192.2K/mo

## What it is and what it does

py_trees is a Python library for building behaviour trees—hierarchical, composable decision-making structures commonly used in robotics and game AI. It provides core primitives like behaviours (leaf nodes representing actions), decorators (wrappers that modify behaviour), composites (sequences, selectors, parallels that combine children), and a blackboard system for sharing state across the tree. Trees can be constructed programmatically or declaratively via XML, serialized to dot graphs for visualization, and rendered in the terminal.

The library is designed for medium-sized decision engines where you need to orchestrate complex conditional logic and state management without writing deeply nested if-else chains. It includes a library of ready-made behaviours and idioms, plus tools for introspection and debugging. Recent versions add typed input/output ports for behaviours and a ForEach decorator for iteration patterns.

Use it for:

- Build a robot control layer that sequences sensor checks, decision logic, and motor commands using tree composites.
- Implement game AI that selects actions (attack, flee, heal) based on game state stored in a shared blackboard.
- Create a workflow engine where tasks are behaviours and control flow (try-catch, retry, parallel execution) is expressed as tree structure.
- Visualize and debug decision logic by rendering the tree to ASCII/Unicode or exporting to dot graphs.
- Define complex conditional logic declaratively in XML rather than imperative code, then parse and execute it at runtime.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

py_trees implements behaviour trees in Python, providing composable decision-making primitives (behaviours, decorators, sequences, selectors, parallels) and a blackboard for data sharing to build medium-sized decision engines.

Yes. py_trees is actively maintained, has low install friction, carries no known vulnerabilities, and offers a clean abstraction for hierarchical decision-making. Install it if you are building a robotics system, game AI, or any medium-complexity state machine that benefits from tree-structured control flow and shared state management.

## Install

pip install py-trees
uv add py-trees
poetry add py-trees

## Installing py_trees

Before you install: Low friction: pure Python wheel with a single runtime dependency (pydot). Actively maintained with a recent release; last commit 2026-07-16 and support for modern Python versions including 3.14.

License in practice: BSD permissive license allows use in commercial and proprietary projects with minimal restrictions; retain license notice in distributions.

Quickstart:

pip install py_trees

import py_trees

# Create a simple behavior tree
root = py_trees.composites.Sequence(name="Root", memory=False)
root.add_child(py_trees.behaviours.Success(name="Task"))
tree = py_trees.trees.BehaviourTree(root=root)
tree.setup_with_descendants()
tree.tick_once()

Verify before relying:

- Whether pydot is required at runtime or only for visualization features
- Exact Python version floor for current releases (requires_python is unspecified)

## Package facts

- License: BSD (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 192.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

behaviour tree implementation, decision tree robotics, behavior tree library python, blackboard data sharing, tree-based decision making, composite behavior patterns, behavior tree visualization, behavior-trees, robotics, decision-engine

[View on SkillFed](https://skillfed.io/packages/py-trees) · [View on PyPI](https://pypi.org/project/py-trees/)