tomli

library2.4.1pypypi✓ verified 29d ago

Tomli is a Python library for parsing TOML (Tom's Obvious, Minimal Language) files, fully compatible with TOML v1.0.0. As of version 2.4.1, it provides a backport of the standard library's `tomllib` module introduced in Python 3.11, ensuring compatibility for earlier Python versions. The library is actively maintained, with regular updates to enhance functionality and maintain compatibility.

serialization data

pip install tomli

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · TOMLI

tomli

serializationpythonv2.4.1

Install

1.6s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.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.95 runs

installs and imports cleanly · install 0.0s · import 0.010s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.010s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

load

✓ from tomli import load

✗ import tomli load = tomli.load

Directly importing the function avoids unnecessary namespace usage.

loads

✓ from tomli import loads

✗ import tomli loads = tomli.loads

Direct import is more concise and aligns with common Python practices.

This example demonstrates how to parse a TOML file named 'config.toml' and print its contents as a Python dictionary.

import tomli with open('config.toml', 'rb') as f: config = tomli.load(f) print(config)

Debug

Known issues

breakingTomli is read-only; it does not support writing TOML files.

fix

Use the 'tomli-w' library for writing TOML files.

affects: All versions

gotchaTomli requires file objects to be opened in binary mode ('rb').

fix

Ensure files are opened with the 'rb' mode when using tomli.load().

affects: All versions

gotchaTomli does not preserve comments or formatting in TOML files.

fix

Be aware that parsing and re-serializing a TOML file will lose comments and original formatting.

affects: All versions

breakingThe TOML configuration file expected by the script was not found.

fix

Ensure that the required TOML file (e.g., 'config.toml') exists in the working directory or at the specified path before running the application.

affects: All versions

breakingThe specified TOML configuration file was not found. Ensure the file path is correct and the file exists in the expected location.

fix

Verify that the TOML file exists at the specified path relative to the script's execution. Provide the correct file path or ensure the file is present.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'tomli'

The 'tomli' package has not been installed in your Python environment.

fix

pip install tomli

FileNotFoundError: [Errno 2] No such file or directory: 'config.toml'

The TOML file specified for loading does not exist at the given path or the path is incorrect relative to where the script is executed.

fix

Verify the existence and correct path of your TOML file, ensuring it's accessible to the script, e.g., 'path/to/your/config.toml'.

tomli.TOMLDecodeError: Invalid escape sequence: '\s'

The TOML file contains an unrecognized escape sequence within a basic string (e.g., '\s', '\v'), which violates TOML's string literal rules.

fix

Escape literal backslashes using `\\` (e.g., change `\s` to `\\s`) or use a literal string; only specific escape sequences are allowed in TOML basic strings.

tomli.TOMLDecodeError: Key 'my_key' has already been defined

The TOML file attempts to define the same key more than once within the same table, which is disallowed by the TOML specification.

fix

Review your TOML file and ensure all keys within any given table are unique; rename or remove duplicate key definitions.

Upgrade

Version history

2.4.1latest on PyPI · released Mar 25, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hukkin/tomli ↗

packagehttps://pypi.org/project/tomli/ ↗

changeloghttps://github.com/hukkin/tomli/blob/master/CHANGELOG.md ↗