Skip to content

What Is in pyproject.toml

The file that defines a Python project: its identity, its packages, and how it is built.

Open pyproject.toml beside this page. The sections appear in the same order as the file.

Section What it does Your action
[project] Names the project and sets the Python version. Change name and description.
dependencies Packages your code needs to run. Keep only what your code uses.
[dependency-groups] Tools for developing and documenting (not needed to run the code). Keep.
[tool.uv] Settings for uv, the environment manager. Keep.
[build-system] and [tool.hatch...] Tells uv how to install your src/ package. Change the package name in two places.

[project]

  • name: the project's name; use lowercase letters and hyphens.
  • description: one line on what the project does.
  • requires-python: the Python version the project needs.
  • dynamic = ["version"]: the version is computed from Git tags, so there is no version number to type here.
  • readme and license-files: point to files in the repository.

Dependencies

dependencies lists packages the code imports. Add one with uv add <package>; uv updates pyproject.toml and uv.lock. Remove packages your project does not use.

[dependency-groups] lists helper tools: dev (testing, formatting, type checking) and docs (documentation). They install with the project but are not needed to run its code.

[tool.uv]

  • default-groups = "all": plain uv sync installs every group.
  • exclude-newer = "7 days": uv ignores package releases less than seven days old, giving time to find problems with new releases.

Build System

[tool.hatch.build.targets.wheel]
packages = ["src/your_package"]

[tool.hatch.build.hooks.vcs]
version-file = "src/your_package/_version.py"

Both paths must match the folder you create under src/. Use underscores in the folder name, even if the project name has hyphens. The folder must exist before you run uv sync. fallback-version is the version used until your first Git tag.

Other Configuration Files

Tool settings live in their own files in the project root:

File Used by
.python-version uv (which Python to install)
prek.toml Git hooks
.ruff.toml Ruff (format and lint)
.pytest.toml pytest
.editorconfig, .gitattributes Editors and Git (whitespace, line endings)
zensical.toml The documentation site
uv.lock Generated by uv; do not edit

◄ Back to 🏠 Guide Home