{"id":2009,"library":"dm-tree","title":"dm-tree: Nested Data Structure Utilities","description":"dm-tree (DeepMind Tree) is a lightweight Python library designed for working with nested data structures such as lists, tuples, and dictionaries. It provides functional tools like `map_structure`, `flatten`, and `unflatten` to apply operations across arbitrary tree-like data. The current stable version is 0.1.10, and it follows an infrequent release cadence focused on stability for its core functionalities.","status":"active","version":"0.1.10","language":"python","source_language":"en","source_url":"https://github.com/deepmind/tree","tags":["data structures","nested data","deepmind","functional programming","tree traversal"],"install":[{"cmd":"pip install dm-tree","lang":"bash","label":"Install dm-tree"}],"dependencies":[{"reason":"Requires Python 3.10 or newer for installation and execution.","package":"python","optional":false}],"imports":[{"note":"The PyPI package `dm-tree` provides the `tree` module, not `dm_tree`.","wrong":"import dm_tree","symbol":"tree","correct":"import tree"},{"symbol":"map_structure","correct":"from tree import map_structure"},{"symbol":"flatten","correct":"from tree import flatten"},{"symbol":"unflatten","correct":"from tree import unflatten"}],"quickstart":{"code":"import tree\n\n# Define a nested data structure\ndata_tree = {\n    'a': [1, 2],\n    'b': {'c': 3, 'd': (4, 5)},\n    'e': 6\n}\n\n# 1. Map a function over all 'leaves' in the structure\ndef increment(x):\n    return x + 1\n\nmapped_tree = tree.map_structure(increment, data_tree)\nprint(f\"Mapped tree: {mapped_tree}\")\n# Expected: {'a': [2, 3], 'b': {'c': 4, 'd': (5, 6)}, 'e': 7}\n\n# 2. Flatten the structure into a list of leaves and a 'structure' object\nleaves, structure = tree.flatten(data_tree)\nprint(f\"Flattened leaves: {leaves}\")\nprint(f\"Original structure (abstracted): {structure}\")\n# Expected: Flattened leaves: [1, 2, 3, 4, 5, 6]\n\n# 3. Unflatten the leaves back into the original structure\nnew_leaves = [x * 10 for x in leaves]\nunflattened_tree = tree.unflatten(structure, new_leaves)\nprint(f\"Unflattened tree: {unflattened_tree}\")\n# Expected: {'a': [10, 20], 'b': {'c': 30, 'd': (40, 50)}, 'e': 60}","lang":"python","description":"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."},"warnings":[{"fix":"Use `import tree` or `from tree import ...` after `pip install dm-tree`.","message":"The PyPI package `dm-tree` should be imported as `import tree`, not `import dm_tree`. This is a common source of 'ModuleNotFoundError'.","severity":"gotcha","affected_versions":"All versions (0.1.x)"},{"fix":"Be 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.","message":"dm-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.","severity":"gotcha","affected_versions":"All versions (0.1.x)"},{"fix":"Ensure your Python environment is 3.10 or newer. Upgrade Python if necessary.","message":"dm-tree requires Python 3.10 or newer. Attempting to install or run on older Python versions will fail or result in compatibility errors.","severity":"breaking","affected_versions":"0.1.0 and later"},{"fix":"Ensure 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.","message":"`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`.","severity":"gotcha","affected_versions":"All versions (0.1.x)"}],"env_vars":null,"search_vec":"'0.1.10':55 'across':44 'appli':42 'arbitrari':45 'cadenc':62 'core':68 'current':51 'data':5,23,49,70,73 'deepmind':11,74 'design':18 'dictionari':30 'dm':2,9 'dm-tree':1,8 'flatten':38 'focus':63 'follow':58 'function':33,69,75 'infrequ':60 'librari':17 'lightweight':15 'like':35,48 'list':27 'map':36 'nest':4,22,72 'oper':43 'program':76 'provid':32 'python':16 'releas':61 'stabil':65 'stabl':52 'structur':6,24,37,71 'tool':34 'travers':78 'tree':3,10,12,47,77 'tree-lik':46 'tupl':28 'unflatten':40 'util':7 'version':53 'work':20","created_at":"2026-04-09T18:39:37.439296+00:00","updated_at":"2026-04-16T14:38:07.758525+00:00","problems":[{"fix":"Ensure the library is installed using `pip install dm-tree`. After installation, it can be imported in Python as `import tree`.","cause":"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`.","error":"ModuleNotFoundError: No module named 'tree'"},{"fix":"First, 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]","cause":"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]","error":"AttributeError: module 'tree' has no attribute 'map_structure'"},{"fix":"Install 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]","cause":"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]","error":"ERROR: Failed building wheel for dm-tree"},{"fix":"Ensure 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.","cause":"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]","error":"TypeError: '<' not supported between instances of 'str' and 'int'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.1.10","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/deepmind/tree","docs":null,"changelog":null,"pypi":"https://pypi.org/project/dm-tree/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}