Помните времена, когда для создания любого пакета в Python был нужен файл setup.py? Это был стандарт де-факто, но у него была одна огромная проблема: чтобы просто узнать, какие зависимости нужны для сборки вашего проекта, установщик (например, pip) должен был запустить этот самый setup.py. Получался замкнутый круг - чтобы собрать пакет, нужно запустить код, который сам еще не собран и не имеет нужных библиотек. Чтобы разорвать этот круг, в экосистеме появились PEP 517 и PEP 518. Эти стандарты полностью изменили то, как мы упаковываем код и распространяем его в 2026 году.
Главные тезисы: что нужно знать
- PEP 518 ввел файл
pyproject.toml, чтобы заранее объявить инструменты для сборки. - PEP 517 создал стандартный интерфейс, позволяющий
pipвзаимодействовать с любой системой сборки, не полагаясь наsetup.py. - Вместе они позволили появиться таким современным инструментам, как Poetry, Flit и Hatch.
- Основная цель - сделать процесс установки пакетов предсказуемым и независимым от конкретного бэкенда.
PEP 518: Конец эпохи «угадывания» зависимостей
До появления PEP 518 установщики пакетов работали вслепую. Если вашему проекту для компиляции расширений на C++ требовался какой-нибудь специальный модуль, pip узнавал об этом только после запуска скрипта установки, когда было уже слишком поздно.
Решением стал файл pyproject.toml. Это декларативный файл конфигурации, который говорит установщику: «Прежде чем ты вообще начнешь что-то собирать, установи вот эти инструменты». Теперь в разделе [build-system] четко прописаны зависимости. Например, если вы используете setuptools, в файле будет указано, что именно он нужен для сборки. Это исключает ситуацию, когда установка обрывается из-за отсутствия базовых инструментов сборки в окружении пользователя.
PEP 517: Универсальный интерфейс для всех
Если PEP 518 решил проблему «что нужно установить», то PEP 517 решил проблему «как именно собирать». Раньше pip был жестко завязан на вызов функции setup() из setuptools. Это означало, что любой новый инструмент сборки должен был либо имитировать setuptools, либо заставлять пользователей использовать свои собственные команды установки.
PEP 517 ввел понятие «бэкенда сборки». Теперь установщик не запускает произвольный Python-код, а вызывает стандартные методы API. Это похоже на то, как разные операционные системы используют разные драйверы для одного и того же типа устройств. Теперь pip просто говорит: «Собери мне wheel-пакет», а выбранный бэкенд (будь то Poetry или Flit) выполняет эту работу по своему внутреннему алгоритму.
| Критерий | PEP 518 | PEP 517 |
|---|---|---|
| Основная цель | Объявление требований для сборки | Стандартизация процесса сборки |
| Ключевой артефакт | Файл pyproject.toml |
API для бэкендов сборки |
| Решаемая проблема | Отсутствие зависимостей перед запуском setup.py |
Привязка pip к конкретному инструменту (setuptools) |
| Результат | Изолированные build-окружения | Возможность выбора любого инструмента упаковки |
Как это работает на практике: от setup.py к современности
Раньше ваш проект выглядел так: был один огромный setup.py, где перемешаны и метаданные (автор, версия), и логика установки, и зависимости. Это было небезопасно, так как выполнение произвольного кода при установке пакета - это дыра в безопасности.
Теперь структура проекта стала чище. Весь «скелет» описывается в pyproject.toml. Вот как это обычно выглядит в современном проекте:
- Создается файл
pyproject.toml. - В нем описывается секция
[build-system], где указанbuild-backend(например,poetry.core.coreилиsetuptools.build_meta). - Указывается список
requires- библиотек, необходимых для создания дистрибутива. - При запуске
pip install .установщик создает временное виртуальное окружение, ставит туда зависимости изrequiresи через API PEP 517 просит бэкенд создатьwheel(бинарный пакет).
Благодаря такому подходу, разработчики получили свободу. Если вам не нравятся громоздкие конфиги setuptools, вы берете Flit для максимально простых проектов или Hatch для сложных версионных схем. При этом для конечного пользователя ничего не меняется: он по-прежнему пишет pip install, и всё просто работает.
Разбор типичных ошибок при сборке
Вы наверняка видели в терминале страшную надпись: ERROR: Could not build wheels for X which use PEP 517 and cannot be.... Эта ошибка - прямой результат работы новых стандартов, когда что-то пошло не так.
Обычно это происходит по двум причинам. Первая - в вашей системе не установлены системные зависимости (например, заголовочные файлы C++ или cmake), которые требуются для компиляции кода. PEP 517 пытается собрать пакет, но бэкенд сообщает о провале. Вторая причина - устаревшая версия pip. Если ваш установщик слишком старый, он просто не понимает спецификации pyproject.toml и пытается искать старый setup.py, которого в проекте может и не быть.
Чтобы это исправить, первым делом обновите инструменты: python -m pip install --upgrade pip setuptools wheel. В 90% случаев это решает проблему, так как обновленный pip корректно обрабатывает цепочку PEP 518 $\rightarrow$ PEP 517.
Будущее управления пакетами в Python
Переход на эти стандарты позволил Python уйти от «императивного» стиля (где мы пишем скрипт, что делать) к «декларативному» (где мы описываем, что хотим получить). Это делает экосистему более стабильной. Теперь метаданные пакета отделены от кода, который его собирает.
В будущем мы увидим еще более глубокую интеграцию этих механизмов. Вероятно, управление зависимостями станет еще более прозрачным, а процесс создания wheel-пакетов будет происходить практически мгновенно за счет оптимизации бэкендов. Важно понимать, что pyproject.toml теперь является единым центром управления не только сборкой, но и настройками линтеров, тестов (например, pytest) и форматтеров кода.
Нужен ли мне все еще setup.py, если есть PEP 517/518?
Для большинства новых проектов - нет. Вы можете полностью заменить его на pyproject.toml. Однако setup.py всё еще может быть полезен, если вам нужна очень сложная, кастомная логика сборки, которую невозможно описать декларативно. Но помните, что в таком случае вы теряете часть преимуществ стандартизации.
Как выбрать между Poetry, Flit и Hatch?
Если вам нужен мощный инструмент для управления зависимостями и публикаций в PyPI «из коробки» - выбирайте Poetry. Если вам нужна максимальная простота и минимализм для небольших библиотек - Flit. Hatch отлично подходит для сложных проектов с разными окружениями и версиями. Все три инструмента работают на базе PEP 517/518.
Что такое wheel и почему он важен в контексте PEP 517?
Wheel - это стандартный формат бинарного распределения в Python. PEP 517 стандартизирует процесс создания именно этого формата. Когда вы устанавливаете пакет, pip сначала ищет готовый wheel, чтобы не компилировать код на вашем компьютере. Если его нет, PEP 517 запускает бэкенд сборки, чтобы создать этот wheel локально.
Почему ошибка PEP 517 возникает даже при наличии всех библиотек?
Часто проблема кроется в «скрытых» зависимостях ОС. Например, пакет может требовать gcc или llvm. Поскольку PEP 517 изолирует процесс сборки, он может не видеть системные пути или требовать специфической версии компилятора, которая не установлена в вашей операционной системе.
Влияют ли эти стандарты на скорость установки пакетов?
Косвенно - да. Благодаря стандартизации стали чаще появляться предсобранные бинарные пакеты (wheels). Теперь установщику не нужно каждый раз запускать тяжелые скрипты сборки, он просто скачивает готовый архив, что ускоряет установку в разы.
Что делать дальше
Если вы до сих пор используете только setup.py, попробуйте перевести свой проект на pyproject.toml. Начните с простого: создайте файл, опишите в нем [build-system] и перенесите зависимости. Вы заметите, что проект стал легче, а установка в чистые окружения - предсказуемее. Если же вы столкнулись с ошибками сборки при установке чужих библиотек, всегда начинайте с обновления pip и проверки системных зависимостей вашего дистрибутива Linux или macOS.