python-box

library7.4.1pypypi✓ verified 27d ago

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.

serialization data

pip install python-box

github ↗package ↗

INSTALL

IMPORT

SIG · PYTHON-BOX

python-box

serializationpythonv7.4.1

Install

2.0s avg

Import

96ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v7.4.1 · 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

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.099s · 20.3MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 2.0s · import 0.093s · 39MB

26MB installed

● package 26MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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}")

Debug

Known issues

breakingSupport 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.

affects: >=7.3.0

breakingThe `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.

affects: >=7.0.0

gotchaSerialization 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.

affects: All

breakingThe 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): ...`

affects: >=7.0.0

Upgrade

Version history

7.4.1latest on PyPI · released Feb 21, 2026

Audit

Dependencies

PyYAMLoptionalFor YAML serialization/deserialization with 'Box.from_yaml' and 'Box.to_yaml'.

tomloptionalFor TOML serialization/deserialization with 'Box.from_toml' and 'Box.to_toml'.

json5optionalFor JSON5 serialization/deserialization with 'Box.from_json5' and 'Box.to_json5'.

toonetoptionalFor TOON serialization/deserialization with 'Box.from_toon' and 'Box.to_toon'.

Agent activity

22 hits · last 30 days

node

Resources

githubhttps://github.com/cdgriffith/Box ↗

packagehttps://pypi.org/project/python-box/ ↗