tomli

When choosing tomli, be aware of the following:

• No Writing Support: tomli is a read-only parser. It does not provide dumps, dump, write, or encode functions. For writing TOML, use Tomli-W.
• No Comment Preservation: tomli returns plain Python dictionaries. It does not preserve comments or formatting from the original TOML file. If you need round-trip parsing that preserves comments, use TOML Kit.
• Basic Types Only: The parser is designed to output only basic data types and standard library types.

Python 3.11+ includes tomllib in the standard library. To write code that uses the standard library when available but falls back to tomli for older Python versions (3.6+), use the following pattern:

1. Define your dependency in your package configuration (e.g., pyproject.toml) as: tomli >= 1.1.0 ; python_version < "3.11"

2. Use this import pattern in your code:

import sys

if sys.version_info >= (3, 11):
    import tomllib
else:
    import tomli as tomllib

tomllib.loads("['Works on all versions']")

You can run performance benchmarks for tomli using tox. There are two ways to run them depending on whether you want to test your local environment or the version currently published on PyPI.

To run benchmarks against your current local state:

tox -e benchmark

To run benchmarks against the latest version of tomli available on PyPI:

tox -e benchmark-pypi

Install the tomli package using pip to use it as a TOML parser in your Python projects.

pip install tomli

If the TOML content is malformed, tomli will raise a tomli.TOMLDecodeError. Note that error messages are informational and may change between versions.

import tomli

try:
    toml_dict = tomli.loads("]] invalid TOML [[")
except tomli.TOMLDecodeError:
    print("Invalid TOML detected.")

Use tomli.loads() to parse a TOML-formatted string into a Python dictionary.

import tomli

toml_str = """
[[players]]
name = "Lehtinen"
number = 26
"""

toml_dict = tomli.loads(toml_str)

Use tomli.load() to parse a TOML file. The file must be opened in binary mode ("rb") to ensure correct UTF-8 decoding and universal newline handling.

import tomli

with open("path_to_file/conf.toml", "rb") as f:
    toml_dict = tomli.load(f)

To avoid float inaccuracies, you can pass a callable to the parse_float argument of tomli.loads(). Passing decimal.Decimal will convert TOML floats into decimal.Decimal objects.

Note: parse_float must return a valid type; passing it a callable that returns dict or list will raise a ValueError.

from decimal import Decimal
import tomli

toml_dict = tomli.loads("precision-matters = 0.982492", parse_float=Decimal)
assert isinstance(toml_dict["precision-matters"], Decimal)

The following table describes how TOML data types are converted into Python objects by tomli:

Use loads() to parse a TOML-formatted string into a Python dictionary. You can optionally provide a parse_float callable to control how floating-point numbers are converted.

import tomli

toml_string = '"key" = "value"'
data = tomli.loads(toml_string)
# data is {'key': 'value'}

Both load() and loads() accept a parse_float parameter. This allows you to use a custom callable (like decimal.Decimal) to handle TOML floats.

Constraint: The provided callable must not return dict or list objects, as this would interfere with the parser's internal structure. If it does, a ValueError will be raised.

from decimal import Decimal
import tomli

toml_string = 'price = 19.99'
# Use Decimal instead of the default float
data = tomli.loads(tomll_string, parse_float=Decimal)

assert isinstance(data['price'], Decimal)