---
id: optree
version: "0.19.1"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# optree — Optimized PyTree Utilities.

License: permissive · Maintenance: active · Downloads: 10.2M/mo

## What it is and what it does

OpTree is a library for working with PyTrees—arbitrarily nested Python containers and custom objects—by providing efficient flatten, unflatten, and map operations. It treats built-in types like dict, list, tuple, namedtuple, and OrderedDict as non-leaf nodes that can be traversed, while custom objects are leaves unless explicitly registered. The core operations are tree flattening (which extracts leaves in deterministic order and captures structure) and unflattening (which reconstructs the tree from leaves and structure), with tree_map built from these primitives.

The package is written in C++ with Python bindings for performance, supports registration of custom container types, and includes a namespace system (optree.pytree) for creating library-specific PyTree utilities. It is actively maintained, has no known vulnerabilities, and provides prebuilt wheels for modern Python versions across multiple platforms, making installation straightforward in most cases.

Use it for:

- Flatten nested model parameters or optimizer states in machine learning frameworks for batch processing.
- Traverse and transform deeply nested configuration dictionaries or JSON-like structures uniformly.
- Register custom container types (e.g., dataclasses) to participate in tree operations without manual recursion.
- Build functional programming patterns that operate on entire tree structures with a single map call.
- Implement library-specific PyTree utilities via the reexport API for downstream packages.

## Worth the install?

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

OpTree provides optimized utilities for flattening, unflattening, and mapping over nested Python container structures (PyTrees) like dicts, lists, tuples, and custom types.

Yes. OpTree is worth installing if you work with nested Python structures in machine learning, scientific computing, or functional programming contexts. It is actively maintained, has no security issues, and provides significant convenience and performance over manual tree traversal. The permissive Apache-2.0 license poses no restriction. Medium install friction is acceptable given the availability of prebuilt wheels for common platforms.

## Install

pip install optree
uv add optree
poetry add optree

## Installing optree

Before you install: Medium install friction due to C++ extension compilation from source; however, prebuilt wheels are available for Python 3.9–3.15 across macOS, Linux, and Windows. Active maintenance with recent releases and no known vulnerabilities.

License in practice: Apache-2.0 is permissive, allowing commercial and private use with minimal restrictions; attribution and license notice are required.

Quickstart:

pip install optree

import optree

tree = {'b': (2, [3, 4]), 'a': 1}
leaves, spec = optree.tree_flatten(tree)
result = optree.tree_map(lambda x: x**2, tree)

Requires Python 3.9+; C++ compiler and cmake needed only if building from source rather than using prebuilt wheels.

Verify before relying:

- Performance characteristics compared to other PyTree implementations (e.g., JAX's tree_util).
- Memory overhead of PyTreeSpec objects for very large or deeply nested structures.
- Compatibility guarantees for custom type registration across OpTree versions.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 10.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytree flatten unflatten, nested container traversal, tree map functional programming, python tree utilities, recursive structure manipulation, pytree registry custom types, tree structure specification, tree-traversal, functional-programming, ml-infrastructure

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