Текст и данные · Инструкция
poetry sync или install что выбрать
`poetry sync` приводит окружение к состоянию, описанному lock-файлом и выбранными группами, включая удаление пакетов, которые больше не должны быть установлены. `poetry install` устанавливает зависимости проекта, но для строгого выравнивания окружения документация Poetry выделяет отдельную команду `sync`.
Короткий ответ
`poetry install` устанавливает зависимости из проекта/lock-файла, а `poetry sync` дополнительно удаляет пакеты, которых нет в выбранном lock-наборе.
Что меняют poetry.lock и dependency groups
При наличии `poetry.lock` обе команды используют зафиксированные версии; без lock-файла Poetry сначала разрешит зависимости. Документация рекомендует `poetry sync` для воспроизводимой чистой установки, но отмечает особые случаи с системной средой и system-site-packages. Группы `--with`, `--without`, `--only`, extras и `--no-root` меняют целевой набор, поэтому параметры CI должны быть явными.
Совет: Перед sync запишите выбранные groups/extras: именно они определяют, что останется в окружении.
Как выполнить задачу и не сломать extras
- Шаг 1: Убедитесь, что `poetry.lock` актуален и находится в Git.
- Шаг 2: Определите набор групп и extras, который должен попасть в конкретную среду.
- Шаг 3: Для чистого virtualenv/CI выполните `poetry sync`; если намеренно используется системное окружение, сверьтесь с ограничениями документации.
- Шаг 4: После установки запустите тесты и проверку приложения, а не ограничивайтесь успешным завершением команды.
Чек-лист: Poetry sync и install: как синхронизировать окружение
- `poetry.lock` актуален относительно `pyproject.toml`.
- Перед sync явно выбраны нужные dependency groups и extras.
- Команда выполняется в нужном virtualenv, который можно безопасно привести к точному состоянию.
- После sync лишние пакеты не возвращаются ручной установкой вне Poetry.
- CI создаёт такое же окружение с теми же группами и проходит тесты.
Когда `poetry sync` особенно полезен
Главный сценарий — CI и давно используемые virtualenv, где могли остаться пакеты от старых веток или удалённых групп. Перед sync проверьте выбранные группы и extras: неуказанные extras при синхронизации могут быть сняты, поэтому итог должен соответствовать реальной задаче. Для контейнерного кэша поддерживаемые опции Poetry позволяют отделять установку зависимостей от root-проекта, но конкретную команду сверяйте с вашей версией. После sync запускайте тесты в этом же окружении, не «долечивая» его ручным pip install.
Важно: Чистый CI должен повторять тот же набор групп и extras, что использовался при локальной проверке.
Когда install и sync дают разный итог
`poetry sync` может удалить вручную установленный пакет. Если он нужен проекту постоянно, добавьте его в декларативную группу зависимостей вместо ручной установки.
Как подтвердить чистое окружение Poetry
Синхронизация успешна, если окружение можно пересоздать из `poetry.lock` и выбранных групп без скрытых пакетов. Если приложение работает только после дополнительного `pip install`, это не причина отказаться от sync, а признак, что зависимость или группа описана неполно и должна быть исправлена в конфигурации проекта.
Предупреждение: Не чините результат ручным pip install — так вы снова создадите состояние, которого нет в lock-конфигурации.
Что учитывать
`poetry sync` может удалить вручную установленный пакет. Если он нужен проекту постоянно, добавьте его в декларативную группу зависимостей вместо ручной установки.
Источники и проверка
Фактическая часть сверена по первичным источникам (в т.ч. Commands). Пример и формулировки — редакция N1RO на 2026-09-23.