Прямой ответ
Конфликт зависимостей возникает, когда два пакета требуют несовместимых версий одной библиотеки. Установка либо завершается ошибкой, либо завершается успешно с нерабочим набором пакетов — второй случай опаснее, поскольку проявляется при выполнении кода.
Типичная ошибка резолвера:
ERROR: Cannot install my-app and requests==2.28.0 because these package
versions have conflicting dependencies.
The conflict is caused by:
package-a 1.4.0 depends on requests<2.29
package-b 2.1.0 depends on requests>=2.31
Чтение сообщения даёт решение: одно из двух ограничений должно быть ослаблено, либо один из пакетов обновлён до версии с совместимыми требованиями.
Диагностика установленного окружения выполняется проверкой согласованности:
$ pip check
package-a 1.4.0 has requirement requests<2.29, but you have requests 2.31.0
Проверка показывает уже существующее расхождение, которое не обнаружила установка. Для просмотра дерева зависимостей используется отдельный инструмент:
$ pipdeptree --reverse --packages requests
requests==2.31.0
- package-b==2.1.0 [requires: requests>=2.31]
- package-a==1.4.0 [requires: requests<2.29]
Обратное дерево показывает, кто именно требует конфликтующую версию, что сокращает поиск причины.
Причины конфликтов:
| Причина | Признак | Устранение |
|---|---|---|
| Фиксация версии в библиотеке | Точная версия в зависимостях библиотеки | Диапазон вместо точной версии |
| Устаревший пакет | Требование прежней версии у неподдерживаемого пакета | Обновление либо замена |
| Слишком широкое ограничение | Отсутствие верхней границы у зависимого | Обоснованная верхняя граница |
| Разные наборы в средах | Работает локально, не работает в конвейере | Файл блокировки |
Основной источник конфликтов, создаваемый собственным кодом, — точная фиксация версии в библиотеке. Библиотека, требующая requests==2.31.0, не позволяет пользователю установить её вместе с пакетом, требующим другой версии; о настройке — в статье про структуру пакета.
Как работает разрешение зависимостей
Понимание механизма объясняет, почему установка иногда занимает минуты и почему результат неочевиден.
Сбор требований. Инструмент собирает ограничения от всех устанавливаемых пакетов, включая транзитивные. Каждое требование описывает допустимый диапазон версий.
Поиск совместимого набора. Резолвер перебирает версии, пытаясь найти набор, удовлетворяющий всем ограничениям. При несовместимости он возвращается назад и пробует другую версию — этот перебор и занимает время.
Применение. После нахождения набора устанавливаются выбранные версии. Если ограничения несовместимы в принципе, установка завершается ошибкой с перечислением конфликтующих требований.
Ключевое свойство: резолвер удовлетворяет объявленным ограничениям, а не фактической совместимости кода. Если два пакета допускают одну версию общей зависимости, но фактически несовместимы с ней, установка пройдёт успешно, а ошибка проявится при выполнении.
Отсюда два практических следствия:
Обоснованность ограничений определяет качество разрешения. Необоснованно широкие диапазоны допускают наборы, которые не работают. Необоснованно узкие — блокируют обновление без причины.
Проверка после установки обязательна. Согласованность объявленных требований не означает работоспособность кода, поэтому прогон тестов после установки не заменяется успешной установкой.
Перебор версий также объясняет, почему добавление одного пакета может изменить версии других: новый набор ограничений требует иного сочетания.
Практика: устранение и предотвращение конфликтов
1. Читайте сообщение резолвера до конца. В нём указаны оба конфликтующих ограничения и пакеты, которые их задают.
2. Проверяйте согласованность окружения. Команда проверки выявляет расхождение, которое установка не обнаружила.
3. Используйте обратное дерево зависимостей. Оно показывает всех потребителей конфликтующей библиотеки, а не только непосредственного.
4. В библиотеках указывайте диапазон с нижней границей. Точная фиксация в библиотеке создаёт конфликт у каждого пользователя; о процессе — в статье про обновление зависимостей.
5. Обосновывайте верхнюю границу. Ограничение сверху без причины блокирует обновление транзитивных зависимостей на годы.
6. Фиксируйте полное дерево в приложении. Файл блокировки устраняет расхождение между средами; о механизме — в статье про lock-файлы.
7. Обновляйте устаревшие пакеты. Конфликт часто разрешается обновлением одной из сторон до версии с актуальными требованиями.
8. Изолируйте неразрешимый конфликт. Если пакеты несовместимы принципиально, они выносятся в отдельные процессы либо один заменяется.
Рекомендации:
- Не игнорируйте предупреждение проверки согласованности. Установленное с расхождением окружение работает до первого вызова конфликтующего кода.
- Избегайте принудительной установки. Игнорирование зависимостей устанавливает несовместимый набор и откладывает проблему.
- Проверяйте конфликт при обновлении, а не при установке. Обновление одного пакета может сломать требования другого.
- Ведите перечень обоснованных ограничений. Верхняя граница с указанием причины предотвращает повторное обсуждение.
- Тестируйте установку полного набора. Установка в чистое окружение выявляет конфликт до развёртывания.
Практический сценарий: падение сервиса после обновления одной зависимости
Контекст: обновление библиотеки для работы с очередями вызвало ошибку импорта в другой части сервиса. Конфликт при установке не сообщался.
- Диагностика. Обновлённая библиотека требовала новую минорную версию общей зависимости и установила её. Другой пакет сервиса требовал прежнюю версию и использовал функцию, удалённую в новой. Проверка согласованности после установки не выполнялась.
- Причина. Зависимости обновлялись по одной, без пересчёта всего дерева. Верхняя граница у второго пакета отсутствовала, поэтому установка сочла набор допустимым.
- Действия. (а) Откатили обновление и восстановили рабочее окружение из блокировки; (б) добавили обоснованную верхнюю границу для второго пакета с указанием причины; (в) обновили второй пакет до версии, совместимой с новой общей зависимостью; (г) добавили проверку согласованности в конвейер после шага установки; (д) перевод обновления зависимостей на пересоздание блокировки целиком, а не по одному пакету.
- Результат. Конфликт обнаруживается на шаге установки в конвейере, а обновление выполняется пересчётом всего дерева с прогоном тестов.
Вывод: конфликт зависимостей проявляется не при установке, а при выполнении кода, если ограничения допускают несовместимый набор. Проверка согласованности окружения и обновление пересчётом всего дерева обнаруживают проблему до развёртывания.
FAQ
Почему установка прошла без ошибки, а код не работает? Ограничения допускали установку, но фактические требования пакетов несовместимы. Проверка согласованности выявляет такое расхождение.
Что делать, если резолвер не находит решение? Ослабить одно из ограничений либо обновить пакет, задающий жёсткое требование. Принудительная установка откладывает проблему.
Нужна ли верхняя граница версии в зависимостях? Только при обоснованной несовместимости. Необоснованное ограничение сверху блокирует обновления на длительное время.
Как предотвратить расхождение между средами? Файлом блокировки с полным деревом зависимостей, общим для всех сред.
Источники: pip docs (Dependency Resolution, pip check), PEP 508 — ссылки в шапке.