Некоторые пакеты Python экосистемы публикуют только предсобранные wheel-дистрибутивы без исходного кода — классический пример PyTorch. Такой пакет физически можно установить только на платформах, для которых существует готовый бинарный дистрибутив, а не на любой платформе через сборку из исходников. Поле required-environments в секции [tool.uv] явно формализует это ограничение прямо в конфиге проекта.
Синтаксис поля
[tool.uv]
required-environments = [
"sys_platform == 'darwin' and platform_machine == 'x86_64'",
]Условие использует синтаксис PEP 508 environment marker — тот же формат, что применяется в extras зависимостей Python пакетов, с переменными вроде sys_platform, platform_machine, python_version.
Что происходит без этого поля
Без явного ограничения uv пытается резолвить зависимости для широкого набора платформ по умолчанию, и для пакета без исходного дистрибутива это может привести к неразрешимой ситуации резолвера — он честно не может найти подходящий wheel для платформы, которую в принципе никто не собирается использовать в реальности.
Второе связанное поле — no-build-isolation-package
[tool.uv]
no-build-isolation-package = ["cchardet"]Решает другую, смежную задачу: отключает изоляцию сборки для конкретных пакетов, чьи build-зависимости должны быть установлены заранее как обычные зависимости проекта, а не в изолированной среде сборки — актуально для пакетов вроде cchardet с нетривиальными требованиями к окружению сборки.
Риск синтаксической ошибки
Опечатка в marker-выражении не всегда выдаёт понятную ошибку сразу — она может тихо привести либо к невозможности установки на платформе, которая должна была поддерживаться, либо к неверной интерпретации условия резолвером.
Как проверить синтаксис перед реальной сборкой
uv Environment Markers Validator проверяет корректность marker-выражений сразу в нескольких pyproject.toml, до того как ошибка проявится в реальной попытке установки.
Итоговый чеклист
required-environments актуален именно для зависимостей без исходного дистрибутива вроде PyTorch, ограничивающих проект набором платформ с готовыми wheel.
Синтаксис условия — стандартный PEP 508 environment marker, тот же формат, что и в extras зависимостей.
no-build-isolation-package решает смежную, но отдельную задачу — отключение изоляции сборки для конкретных пакетов, а не ограничение платформ.