Python Box

7.4.1 · active · verified Thu Apr 09

python-box is an active library that provides an advanced Python dictionary with dot notation access, allowing dictionary keys to be accessed as attributes. It simplifies working with deeply nested data structures and offers various serialization methods (JSON, YAML, TOML, JSON5, TOON) and other utility classes. The current version is 7.4.1, and it maintains a regular release cadence with updates and bug fixes.

Warnings

breaking Support for older Python versions (3.8, 3.9) has been removed in recent major versions. Ensure your project runs on Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or higher. For example, Python 3.9 was dropped in 7.4.0, and 3.8 in 7.3.0.
breaking The `box_dots` functionality changed in v7.0.0. Keys containing periods (`.`) are now automatically treated as nested keys by default, potentially altering data structure interpretation for existing code.
Fix: If you need keys with periods to be treated literally without nesting, use the `box_dots_filter` parameter to specify which keys should be excluded from dot notation parsing, or use `box_dots_exclude` (added in 7.4.0) to explicitly list keys to ignore.
gotcha Serialization methods like `Box.from_yaml`, `Box.to_toml`, etc., require specific optional dependencies (e.g., `PyYAML`, `toml`) to be installed separately. Failing to install them will result in `ImportError`.
Fix: Install the required dependencies for the serialization format you intend to use. For example, `pip install python-box[yaml]` or `pip install python-box[all]` for all optional features.
breaking The signature for `default_function` when defining default behavior in `DefaultBox` was changed in v7.0.0, now including `box_instance` and `key` parameters.
Fix: Update the signature of your `default_function` to accept `box_instance` and `key` as arguments, even if you don't use them, e.g., `def my_default_func(box_instance, key): ...`

Install

pip install python-box Base Installation
pip install python-box[all] With all optional dependencies
pip install python-box[yaml,toml,json5,toon] With specific optional dependencies

Imports

Box
```
from box import Box
```
ConfigBox
```
from box import ConfigBox
```
DefaultBox
```
from box import DefaultBox
```
BoxList
```
from box import BoxList
```
ShorthandBox
```
from box import ShorthandBox
```
BoxKeyError
```
from box import BoxKeyError
```

Quickstart

This quickstart demonstrates how to create a `Box` object from a standard Python dictionary and access its elements using convenient dot notation. It also shows how to modify and add new attributes, and highlights the behavior when accessing non-existent keys (raising an AttributeError by default).

from box import Box

# Create a Box from a dictionary
config = Box({
    'application': {
        'name': 'MyAwesomeApp',
        'version': '1.0.0',
        'settings': {
            'debug_mode': True,
            'log_level': 'INFO'
        }
    },
    'database': {
        'host': 'localhost',
        'port': 5432
    }
})

# Access items using dot notation
print(f"App Name: {config.application.name}")
print(f"Debug Mode: {config.application.settings.debug_mode}")

# Modify items
config.database.port = 5433
print(f"New DB Port: {config.database.port}")

# Add new items
config.application.author = 'AI Agent'
print(f"App Author: {config.application.author}")

# Example with missing key (will raise AttributeError without default_box_create_on_get)
try:
    print(config.non_existent_key)
except AttributeError as e:
    print(f"Caught expected error: {e}")

view raw JSON →