Install & Compatibility
Where this runs
tested against v2.3.0 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.109s · 19.9MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 1.9s · import 0.098s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
load
✓ from dom_toml import load
loads
✓ from dom_toml import loads
dump
✓ from dom_toml import dump
dumps
✓ from dom_toml import dumps
Config
✓ from dom_toml.config import Config
For structured configuration parsing (requires 'config' extra).
Demonstrates loading TOML from a string, modifying the resulting dictionary, and then dumping it back to a TOML string and writing it to a file. This covers the core read/write functionality.
import os
from dom_toml import loads, dumps
# Example TOML string
toml_data_str = """
[project]
name = "my-package"
version = "0.1.0"
authors = [
{ name = "Alice", email = "alice@example.com" },
{ name = "Bob", email = "bob@example.com" }
]
"""
# Load TOML from a string
config = loads(toml_data_str)
print("Loaded TOML:", config)
# Expected: {'project': {'name': 'my-package', 'version': '0.1.0', 'authors': [{'name': 'Alice', 'email': 'alice@example.com'}, {'name': 'Bob', 'email': 'bob@example.com'}]}}
# Modify data (optional)
config['project']['license'] = 'MIT'
# Dump Python dict to TOML string
updated_toml_str = dumps(config)
print("\nUpdated TOML string:\n", updated_toml_str)
# Example of writing to a file (requires a temporary file)
import tempfile
with tempfile.NamedTemporaryFile(mode='w+', delete=False, suffix='.toml') as tmp_file:
tmp_file_name = tmp_file.name
dump(config, tmp_file_name)
print(f"\nTOML written to {tmp_file_name}. Contents:\n")
with open(tmp_file_name, 'r') as f:
print(f.read())
# Clean up temporary file
os.remove(tmp_file_name)
Debug
Known issues
breakingIn version 2.0.0, the `encoder` and `decoder` parameters for `dump`, `dumps`, `load`, and `loads` functions must now be instances or types of `dom_toml.encoder.TomlEncoder` or `dom_toml.decoder.TomlDecoder` respectively. Passing arbitrary callables is no longer supported directly.fixEnsure that custom encoders/decoders passed to the functions are subclasses or instances of the library's `TomlEncoder` or `TomlDecoder` classes. If you were passing a simple function, wrap it in a custom `TomlEncoder`/`TomlDecoder` subclass.
affects: >=2.0.0
gotchaWhen using `dom_toml.load()` with a file object, it is generally recommended to open the file in binary read mode (`'rb'`). This ensures correct handling of UTF-8 encoding and universal newlines, which is in line with the TOML specification.fixAlways open TOML files in binary mode: `with open('config.toml', 'rb') as f: config = load(f)`. affects: All versions
gotchaUnlike Python's built-in `tomllib` (Python 3.11+) or the `tomli` library, `dom-toml` is a separate implementation that provides both reading and writing capabilities. It does not use `tomli` or `tomllib` internally, meaning its behavior and features might differ slightly.fixBe aware that `dom-toml` offers its own unique set of features for TOML parsing and serialization beyond the standard `tomli`/`tomllib` API. Consult `dom-toml`'s documentation for specific functionalities and custom encoders/decoders.
affects: All versions
gotchaWhile TOML supports nested structures, excessively deep nesting or complex arrays of tables can become difficult to read and maintain. This is a general characteristic of the TOML format, not specific to `dom-toml`.fixConsider simplifying your TOML configuration schemas to minimize deep nesting and complex structures, especially for human-edited files. Utilize the `dom_toml.config` module for more structured Python-side handling of configurations if complexity is unavoidable.
affects: All versions (TOML specification)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dom_toml'
The `dom-toml` package is not installed in the current Python environment or is imported with the incorrect module name (using a hyphen instead of an underscore).
fixEnsure the package is installed using `pip install dom-toml` and imported as `import dom_toml` or `from dom_toml import load, dumps` etc.
dom_toml.parser.BadConfigError: <error message related to TOML configuration>
The TOML file or string being parsed contains invalid syntax or structural issues that violate the TOML specification or the expected configuration schema by `dom-toml`.
fixReview the TOML content for syntax errors, incorrect data types, missing required keys, or structural problems. Refer to the TOML specification and `dom-toml`'s documentation for correct formatting. The specific error message will provide more details.
TOML parse error at line X, column Y: <message>
The TOML input string or file contains a syntax error at the indicated line and column, preventing `dom-toml` from successfully parsing it.
fixExamine the TOML content at the specified line and column. Common issues include unclosed strings, incorrect array or table definitions, missing delimiters, or invalid character usage. Use a TOML linter or validator to help identify the exact syntax problem.
KeyError: '<key_name>'
You are attempting to access a key in the parsed TOML data (which behaves like a Python dictionary) that does not exist in the TOML configuration.
fixVerify that the key name is spelled correctly and that it actually exists in your TOML structure. You can use dictionary methods like `.get('key_name', default_value)` to provide a default value if the key might be optional, or check for key existence using `if 'key_name' in config:` before accessing it. Upgrade
Version history
2.3.0latest on PyPI · released Jan 22, 2026
Audit
Dependencies
attrsoptionalRequired for the 'config' module which provides structured configuration classes.