How do you read TOML with tomllib in Python 3.11+?

Q: How do you read TOML with tomllib in Python 3.11+?

**Target Audience:** Python developers who configure apps or tools, explained from zero **Difficulty:** Easy **Python version:** Behaviour checked on CPython 3.11, 3.12 and 3.13 (and in the page's Pyodide 3.11 runtime) > **How to read this doc:** Each idea is explained in plain language first, then tagged with `📌 Interview term:` so you also learn the exact words an interviewer expects. Every output block in the **Verified** section was copied from a real run of the examples on this page. ## 1. Why This Even Matters — A Story First Every program has settings: which port to listen on, the database address, how many retries. You could write them in Python, but then a typo in a settings file can run code. You could write JSON, but JSON has no comments and is fussy about commas, which is miserable for a file humans edit by hand. **TOML** ("Tom's Obvious Minimal Language") was designed as the middle ground: it reads like an old-fashioned `.ini` file, with `key = value` lines and `[sect

The problem

Question presented to candidate: "Your service keeps its settings in a TOML file, and you are on Python 3.11. How do you read it with the standard library, what do you get back, and what can trip you up?"

What a strong answer should cover:

tomllib joined the standard library in Python 3.11 (PEP 680); tomllib.load(f) reads a file opened in binary mode ("rb"), tomllib.loads(s) parses a str
The result is a plain dict: tables become nested dicts, arrays become lists, arrays of tables ([[x]]) become lists of dicts, and dates and times become datetime objects
Invalid documents raise tomllib.TOMLDecodeError, a ValueError subclass, with line and column; duplicate keys are errors, unlike JSON
tomllib is read-only: there is no dump; use the third-party tomli-w to write or tomlkit to edit while keeping comments
Practical patterns: parse_float=Decimal, defaults merged with | or .get, and tomli as a fallback on Python 3.10 and older
Typical use: reading pyproject.toml or an app config at start-up; TOML has no null, so a missing key means "not set"

Code / implementation expected: Yes — with open(path, "rb") as f: config = tomllib.load(f) and reading a nested value.

tomllib
config
python3.11

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Python developers who configure apps or tools, explained from zero Difficulty: Easy Python version: Behaviour checked on CPython 3.11, 3.12 and 3.13 (and in the page's Pyodide 3.11 runtime)

How to read this doc: Each idea is explained in plain language first, then tagged with 📌 Interview term: so you also learn the exact words an interviewer expects. Every output block in the Verified section was copied from a real run of the examples on this page.

1. Why This Even Matters — A Story First

Every program has settings: which port to listen on, the database address, how many retries. You could write them in Python, but then a typo in a settings file can run code. You could write JSON, but JSON has no comments and is fussy about commas, which is miserable for a file humans edit by hand.

TOML ("Tom's Obvious Minimal Language") was designed a

The solution is hidden so you can try first

11 min read · 11 sections

Run the code

Edit the code and run it here. Each console line with an expected value becomes a test.

Pythontomllib.loads: every TOML type, nested tables, arrays of tables, and TOMLDecodeError

Practice

Pythontomllib.load with rb, the text-mode error, parse_float=Decimal, defaults, and no writer