Install & Compatibility
Where this runs
tested against v0.1.10 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.270s · 88MB
74MB installed
● package 74MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tree
✓ import tree
✗ import dm_tree
The PyPI package `dm-tree` provides the `tree` module, not `dm_tree`.
map_structure
✓ from tree import map_structure
flatten
✓ from tree import flatten
unflatten
✓ from tree import unflatten
This quickstart demonstrates the core functionalities of `dm-tree`: `map_structure` for applying a function to all 'leaf' elements, and `flatten`/`unflatten` for converting a nested structure into a flat list of elements and back again, preserving the original structure.
import tree
# Define a nested data structure
data_tree = {
'a': [1, 2],
'b': {'c': 3, 'd': (4, 5)},
'e': 6
}
# 1. Map a function over all 'leaves' in the structure
def increment(x):
return x + 1
mapped_tree = tree.map_structure(increment, data_tree)
print(f"Mapped tree: {mapped_tree}")
# Expected: {'a': [2, 3], 'b': {'c': 4, 'd': (5, 6)}, 'e': 7}
# 2. Flatten the structure into a list of leaves and a 'structure' object
leaves, structure = tree.flatten(data_tree)
print(f"Flattened leaves: {leaves}")
print(f"Original structure (abstracted): {structure}")
# Expected: Flattened leaves: [1, 2, 3, 4, 5, 6]
# 3. Unflatten the leaves back into the original structure
new_leaves = [x * 10 for x in leaves]
unflattened_tree = tree.unflatten(structure, new_leaves)
print(f"Unflattened tree: {unflattened_tree}")
# Expected: {'a': [10, 20], 'b': {'c': 30, 'd': (40, 50)}, 'e': 60}
Debug
Known issues
gotchaThe PyPI package `dm-tree` should be imported as `import tree`, not `import dm_tree`. This is a common source of 'ModuleNotFoundError'.fixUse `import tree` or `from tree import ...` after `pip install dm-tree`.
affects: All versions (0.1.x)
gotchadm-tree's core functions (e.g., `map_structure`) define 'nested structures' (nodes) as `dict`, `list`, `tuple`, `namedtuple`, and `collections.OrderedDict`. All other types are considered 'leaves'. This can be unexpected for custom objects that you might consider iterable or 'tree-like' but don't fall into these categories.fixBe aware of this classification. For custom classes, ensure they mimic standard containers if you want them treated as nodes, or explicitly implement `_fields` and `_asdict` if you want `namedtuple`-like behavior.
affects: All versions (0.1.x)
breakingdm-tree requires Python 3.10 or newer. Attempting to install or run on older Python versions will fail or result in compatibility errors.fixEnsure your Python environment is 3.10 or newer. Upgrade Python if necessary.
affects: 0.1.0 and later
gotcha`tree.map_structure` is strict about structure matching. All arguments to `map_structure` must have the same nested structure. If the structures differ (e.g., one has a list of 3 items, another a list of 2), it will raise a `ValueError`.fixEnsure all structures passed to `map_structure` have identical nesting and container types at corresponding positions. If you need to map over structures with differing shapes, you'll need to handle the differences before mapping or use `flatten` and manually map the leaves.
affects: All versions (0.1.x)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tree'
Users often try to import `tree` directly, but the package name on PyPI is `dm-tree`. The installed library is then imported as `import tree`, but the installation itself needs to refer to `dm-tree`.
fixEnsure the library is installed using `pip install dm-tree`. After installation, it can be imported in Python as `import tree`.
AttributeError: module 'tree' has no attribute 'map_structure'
This error typically occurs if the `dm-tree` library (which is imported as `tree`) is not correctly installed, if an incompatible version is installed, or if there's a local file named `tree.py` shadowing the installed library. [1]
fixFirst, ensure `dm-tree` is installed and up to date with `pip install -U dm-tree`. If the problem persists, check your project directory and Python path for any custom `tree.py` files that might be conflicting with the `dm-tree` library. [1]
ERROR: Failed building wheel for dm-tree
This installation error arises when `pip` attempts to build `dm-tree` from source (e.g., if a pre-compiled wheel isn't available for your Python version or OS). It often indicates missing system build dependencies like CMake, or an incompatibility with the Python version (e.g., Python 3.12 might not have wheels yet). [8, 14, 15, 18]
fixInstall build tools (e.g., CMake on Linux/macOS, or Visual C++ Build Tools on Windows). For Python version incompatibilities, try installing `dm-tree` with a Python version for which pre-compiled wheels are known to exist (e.g., Python 3.9-3.11 for some versions of `dm-tree`). [14, 15]
TypeError: '<' not supported between instances of 'str' and 'int'
This error occurs when using `dm-tree` (often indirectly through libraries like JAX that use it for pytrees) with dictionaries that have mixed key types (e.g., a dictionary containing both string and integer keys). `dm-tree` (or JAX's pytree implementation) may attempt to sort dictionary keys, and Python cannot compare strings and integers directly. [24]
fixEnsure that dictionaries processed by `dm-tree` (or libraries utilizing it) have homogeneous key types (all strings or all integers) if sorting is implied. Alternatively, convert all keys to a common, sortable type if mixed keys are necessary for the application's logic.
Upgrade
Version history
0.1.10latest on PyPI · released Mar 31, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer for installation and execution.