Tomli

2.4.1 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install tomli

Common errors

error ModuleNotFoundError: No module named 'tomli' ↓

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

fix

pip install tomli

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

cause 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'.

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

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

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

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

Warnings

breaking Tomli is read-only; it does not support writing TOML files. ↓

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

gotcha Tomli requires file objects to be opened in binary mode ('rb'). ↓

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

gotcha Tomli 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.

breaking The 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.

breaking The 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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.01s 17.9M

3.10 slim (glibc) - - 0.01s 18M

3.11 alpine (musl) - - 0.01s 20.3M

3.11 slim (glibc) - - 0.01s 21M

3.12 alpine (musl) - - 0.01s 12.2M

3.12 slim (glibc) - - 0.01s 13M

3.13 alpine (musl) - - 0.01s 11.8M

3.13 slim (glibc) - - 0.01s 12M

3.9 alpine (musl) - - 0.01s 17.4M

3.9 slim (glibc) - - 0.01s 18M

Imports

load
wrong
```
import tomli
load = tomli.load
```
correct
```
from tomli import load
```
Directly importing the function avoids unnecessary namespace usage.
loads
wrong
```
import tomli
loads = tomli.loads
```
correct
```
from tomli import loads
```
Direct import is more concise and aligns with common Python practices.

Quickstart stale last tested: 2026-04-23

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)