How do pyproject.toml, tomllib, and uv/pyproject workflows fit together?

Q: How do pyproject.toml, tomllib, and uv/pyproject workflows fit together?

**Target Audience:** Beginners who have run `pip install` but never set up a project from scratch; also experienced developers who want the precise names of each part. **Difficulty:** Easy **Python version:** The `tomllib` examples were run on CPython 3.11 (python3.11 and the in-page Pyodide 0.25.1 runtime, which is CPython 3.11.3). The uv commands were run with uv 0.11.32 against CPython 3.12.3. > **How to read this doc:** Every idea is explained in plain language first, then tagged with `📌 Interview term:` so you also learn the exact word an interviewer expects. Outputs in the **Verified** section, and the uv files shown, were copied from real runs. ## 1. Why This Even Matters — A Story First Imagine a restaurant kitchen with a single clipboard by the door. The top sheet tells the delivery driver how to load the van. The second sheet is the menu: the dish names and the ingredients each one needs. The third sheet is staff-only: what the cooks need for practice and cleaning, which

The problem

Question presented to candidate: "Most new Python projects start with a single pyproject.toml file and a tool like uv. Explain what goes in that file, who reads which part of it, where tomllib fits in, and what actually happens when you run uv add, uv sync and uv run."

What a strong answer should cover:

pyproject.toml is one TOML file with standard tables: [build-system] (PEP 518: how to build the package), [project] (PEP 621: name, version, requires-python, dependencies), [dependency-groups] (PEP 735: dev-only groups such as test and lint) and a free namespace [tool.NAME] for each tool's own settings.
tomllib (standard library since Python 3.11, PEP 680) is the read-only parser: tomllib.load() needs a file opened in binary mode, tomllib.loads() takes a string, and there is no dump().
The uv loop: uv add edits pyproject.toml, resolves and writes the exact versions to uv.lock, and installs into .venv; uv sync makes .venv match the lock; uv run syncs and then runs the command inside that environment.
Ranges vs pins: pyproject.toml declares the ranges you accept, uv.lock records the exact versions and hashes the resolver chose; commit both, never commit .venv.
The build side: a frontend (uv build, pip) reads [build-system], installs the backend it names (hatchling, setuptools, uv_build) and calls it to make an sdist and a wheel.
A bonus detail: PEP 723 inline script metadata (# /// script) puts the same TOML inside a single script, and uv run script.py honours it.

Code / implementation expected: Optional — reading a pyproject with tomllib and sketching the four tables is a strong start; no build needed.

toml
pyproject
packaging

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: Beginners who have run pip install but never set up a project from scratch; also experienced developers who want the precise names of each part. Difficulty: Easy Python version: The tomllib examples were run on CPython 3.11 (python3.11 and the in-page Pyodide 0.25.1 runtime, which is CPython 3.11.3). The uv commands were run with uv 0.11.32 against CPython 3.12.3.

How to read this doc: Every idea is explained in plain language first, then tagged with 📌 Interview term: so you also learn the exact word an interviewer expects. Outputs in the Verified section, and the uv files shown, were copied from real runs.

1. Why This Even Matters — A Story First

Imagine a restaurant kitchen with a single clipboard by the door. The top sheet tells the delivery driver how to load the van. The second sheet is the menu: the dish names and the ingredients

The solution is hidden so you can try first

9 min read · 10 sections

Run the code

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

PythonParse a pyproject.toml with tomllib (tables, binary mode, errors)

Practice

PythonWhat a tool does with it: dependency groups, names, requires-python, PEP 723