# pyproject.toml

> Стандартный файл конфигурации Python-проекта — система сборки, метаданные пакета, зависимости и настройки инструментов.

Источник: https://llmdocs.ru/wiki/pyproject-toml/ · обновлено 2026-11-09 · лицензия CC BY-SA 4.0

- **Тип**: файл конфигурации проекта
- **Формат**: TOML
- **Язык**: Python
- **Стандарты**: PEP 518 (2016), PEP 517, PEP 621 (2020), PEP 735
- **Основные таблицы**: `[build-system]`, `[project]`, `[dependency-groups]`, `[tool.*]`
- **Бэкенды сборки**: setuptools, hatchling, flit-core, pdm-backend, poetry-core, maturin
- **Спецификация**: [packaging.python.org](https://packaging.python.org/en/latest/specifications/pyproject-toml/)
**pyproject.toml** — стандартный файл конфигурации проекта на [Python](https://llmdocs.ru/wiki/python.md), размещаемый в корне репозитория. В нём указываются система сборки пакета, его метаданные (имя, версия, зависимости, точки входа) и настройки инструментов разработки — линтеров, форматировщиков, тестовых фреймворков. Файл пришёл на смену разрозненным `setup.py`, `setup.cfg`, `requirements.txt` и множеству отдельных конфигов, объединив их в одном месте.

## История

Долгое время пакет Python описывался исполняемым скриптом `setup.py`. Чтобы узнать хотя бы зависимости, нужно было запустить произвольный код, а сам скрипт требовал заранее установленного setuptools.

Стандартизация шла в несколько шагов:

| PEP | Год | Что добавил |
|---|---|---|
| PEP 518 | 2016 | файл `pyproject.toml` и таблицу `[build-system]`: какие пакеты нужны для сборки[2] |
| PEP 517 | 2017 | единый интерфейс между установщиком и **бэкендом сборки**[3] |
| PEP 621 | 2020 | таблицу `[project]` со стандартными метаданными[4] |
| PEP 660 | 2021 | установку в режиме разработки (editable) через бэкенд |
| PEP 735 | 2024 | `[dependency-groups]` — группы зависимостей для разработки, не попадающие в пакет[5] |

Формат TOML выбран за простоту и однозначность; с Python 3.11 его чтение встроено в стандартную библиотеку (модуль `tomllib`).[7]

## Структура

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "weather-cli"
version = "0.3.0"
description = "Прогноз погоды в терминале"
readme = "README.md"
requires-python = ">=3.11"
license = "MIT"
authors = [{ name = "Иван Петров" }]
dependencies = [
    "httpx>=0.27",
    "rich>=13",
]

[project.optional-dependencies]
yaml = ["pyyaml>=6"]

[project.scripts]
weather = "weather_cli.main:run"

[dependency-groups]
dev = ["pytest>=8", "ruff"]

[tool.ruff]
line-length = 100

[tool.pytest.ini_options]
testpaths = ["tests"]
```

## Таблицы

**`[build-system]`** сообщает установщику, какие пакеты поставить во временное окружение и какой бэкенд вызвать, чтобы собрать wheel или sdist. Благодаря этому [pip](https://llmdocs.ru/wiki/pip-pypi.md) может собрать любой проект, не зная, каким инструментом он сделан.

**`[project]`** — стандартные метаданные:[1]

- `name`, `version` (или `dynamic = ["version"]`, если версию вычисляет бэкенд, например из тега [Git](https://llmdocs.ru/wiki/git.md));
- `dependencies` — зависимости в формате спецификаторов версий;
- `optional-dependencies` — «экстра», устанавливаемые как `pip install weather-cli[yaml]`;
- `requires-python` — поддерживаемые версии интерпретатора;
- `scripts` — консольные команды, создаваемые при установке;
- `license` — выражение SPDX (см. [Лицензии ПО (MIT, GPL, Apache, CC)](https://llmdocs.ru/wiki/software-licenses.md)).

**`[dependency-groups]`** хранит зависимости, нужные только при разработке (тесты, линтеры, документация), — они не публикуются вместе с пакетом.

**`[tool.<имя>]`** — пространство для настроек сторонних инструментов: [Ruff](https://llmdocs.ru/wiki/ruff.md), [pytest](https://llmdocs.ru/wiki/pytest.md), [mypy](https://llmdocs.ru/wiki/mypy-pyright.md), coverage, Black и других. Каждый инструмент читает только свою таблицу.

## Бэкенды сборки

| Бэкенд | Особенность |
|---|---|
| setuptools | исторический стандарт, поддерживает расширения на C |
| hatchling | современный, по умолчанию в Hatch |
| flit-core | минималистичный, для чистого Python |
| pdm-backend | бэкенд менеджера PDM |
| poetry-core | бэкенд Poetry |
| maturin | сборка расширений на Rust (PyO3) |

Менеджеры проектов — Poetry, PDM, Hatch, [uv](https://llmdocs.ru/wiki/uv.md) — используют `pyproject.toml` как основной файл. Точные версии всего дерева зависимостей при этом хранятся отдельно, в файле блокировки (`uv.lock`, `poetry.lock`), который самим `pyproject.toml` не заменяется.

## Типичные ошибки

- Указание зависимостей одновременно в `pyproject.toml` и `requirements.txt` с расхождениями.
- Отсутствие таблицы `[build-system]` — тогда инструменты по умолчанию предполагают setuptools.
- Жёсткая фиксация версий (`==`) в `dependencies` библиотеки: это мешает пользователям совмещать её с другими пакетами. Фиксируют версии приложения в файле блокировки, а в библиотеке задают диапазоны.

## Аналоги

Похожую роль играют `package.json` в мире [Node.js](https://llmdocs.ru/wiki/nodejs.md), `Cargo.toml` в Rust (см. [Cargo и crates.io](https://llmdocs.ru/wiki/cargo.md)) и `go.mod` в Go (см. [Go-модули (go.mod)](https://llmdocs.ru/wiki/go-modules.md)).

## См. также

- [pip и PyPI](https://llmdocs.ru/wiki/pip-pypi.md)
- [uv (менеджер пакетов)](https://llmdocs.ru/wiki/uv.md)
- [Виртуальные окружения (venv)](https://llmdocs.ru/wiki/venv.md)
- [PEP](https://llmdocs.ru/wiki/pep.md)

## Источники

1. [pyproject.toml specification — Python Packaging User Guide](https://packaging.python.org/en/latest/specifications/pyproject-toml/)
2. [PEP 518 — Specifying Minimum Build System Requirements](https://peps.python.org/pep-0518/)
3. [PEP 517 — A build-system independent format for source trees](https://peps.python.org/pep-0517/)
4. [PEP 621 — Storing project metadata in pyproject.toml](https://peps.python.org/pep-0621/)
5. [PEP 735 — Dependency Groups in pyproject.toml](https://peps.python.org/pep-0735/)
6. [TOML specification](https://toml.io/en/)
7. [tomllib — Parse TOML files](https://docs.python.org/3/library/tomllib.html)