Project configuration
Describe a project declaratively and distinguish declared dependencies from resolved versions.
On this page
The concept
pyproject.toml stores project metadata and tool configuration. The project table describes the package and its runtime requirements. Dependency groups can describe development tools without making them runtime requirements. tomllib reads TOML data; it does not execute it as Python.
uv is an optional project-management tool. uv sync --locked --group dev recreates the declared environment using uv.lock. uv run executes a command in the managed environment. uv.lock records resolved distributions and hashes; regenerate it with uv rather than editing it manually.
Worked example
import tomllib
metadata = '\n[project]\nname = "learning-python"\nversion = "0.1.0"\nrequires-python = ">=3.12"\ndependencies = []\n\n[dependency-groups]\ndev = ["pytest", "ruff", "mypy"]\n'
project = tomllib.loads(metadata)
print(project["project"]["name"])
print("development tools:", project["dependency-groups"]["dev"])Trace the result
- The metadata string is application data containing TOML, so it remains in the Python example.
- tomllib.loads converts that text into nested dictionaries.
- The program reads the project name and development-tool group by key.
learning-python
development tools: ['pytest', 'ruff', 'mypy']Line-by-line walkthrough
Line 1: import tomllib
Load tomllib (TOML data parsing). Importing makes these names available; it is not a call to every function in the module.
Line 3: metadata = '\n[project]\nname = "learning-python"\nversion = "0.1.0"\nrequires-python = ">=3.12"\ndependencies = []\n\n[dependency-groups]\ndev = ["pytest", "ruff", "mypy"]\n'
Evaluate '\n[project]\nname = "learning-python"\nversion = "0.1.0"\nrequires-python = ">=3.12"\ndependencies = []\n\n[dependency-groups]\ndev = ["pytest", "ruff", "mypy"]\n', then bind or update metadata with the result. This literal is prepared example data. Assignment itself does not imply a deep copy.
Line 4: project = tomllib.loads(metadata)
Evaluate tomllib.loads(metadata), then bind or update project with the result. The call finishes before its return value is bound; a failed call does not produce a successful assignment. Assignment itself does not imply a deep copy.
Line 5: print(project["project"]["name"])
Evaluate the print arguments from the current state and display them. sep controls separators and end controls the ending when those options are provided. Displaying a value does not return that value from the surrounding function.
Line 6: print("development tools:", project["dependency-groups"]["dev"])
Evaluate the print arguments from the current state and display them. sep controls separators and end controls the ending when those options are provided. Displaying a value does not return that value from the surrounding function.
Common mistake
The lockfile and the declaration solve different problems. A copied virtual environment is not a replacement for either.