#Что происходит и когда возникает ошибка
Перед обновлением Python-окружения полезно сохранить точные версии и проверить, какие прямые и косвенные зависимости установлены. pip list, pip freeze и pip check решают разные задачи и не заменяют резервную копию проекта.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Нет снимка предыдущих версийБез зафиксированного списка сложно повторить рабочее окружение. | После обновления неизвестно, какие зависимости изменились | Сохранить pip freeze перед работами. |
| Есть скрытые конфликтыОбновление поверх повреждённого набора может усложнить диагностику. | pip check сообщает несовместимость уже установленных пакетов | Исправлять несовместимости на копии. |
| Перечень смешивает лишние пакетыИспользуется общий Python или venv с чужими пакетами. | pip list показывает библиотеки других задач | Создать чистое окружение на основе требований проекта. |
#Подробная диагностика и исправление
- Сначала определите границы проектаОткройте корневую папку приложения и найдите
requirements.txt,pyproject.tomlили зафиксированный файл зависимостей. Важно понимать, какой Python запускает именно это приложение: в IDE и службах он может отличаться от терминального.
- Проверьте интерпретатор и окружениеВ терминале приложения выполните команду, которая покажет исполняемый Python, префикс venv и путь к pip. Если префиксы совпадают, перед вами глобальная установка: не обновляйте её без согласования с другими программами.Linux · Терминал (Bash)КомандаОбычный терминал; только чтение.
python -c "import sys; print(sys.executable, sys.prefix, sys.base_prefix)"python -m pip --version
- Сохраните список с точными версиямиВ корне проекта создайте файл
before-upgrade.txt:pip freezeперечислит установленное в формате требований. Этот список включает и непрямые зависимости; он не заменяет проектное описание прямых требований. Проверьте, не содержит ли файл приватных адресов Git или токенов перед отправкой кому-либо. - Создаёт локальный файл; для проекта лучше хранить копию в защищённом местеLinux · Терминал (Bash)КомандаСоздаёт локальный файл; для проекта лучше хранить копию в защищённом месте.
python -m pip freeze > before-upgrade.txt
- Сделайте читаемую инвентаризациюКоманда
pip list --format=jsonсоздаёт машиночитаемый перечень,pip list --outdatedпоказывает обновления, доступные в вашем индексе. Последняя требует доступа к сети и не означает, что каждое обновление совместимо с проектом. - Сведения только для текущего интерпретатора, без установкиLinux · Терминал (Bash)КомандаСведения только для текущего интерпретатора, без установки.
python -m pip list --format=jsonpython -m pip list --outdated
- Проверьте согласованность зависимостейВыполните
python -m pip check. При успехе увидитеNo broken requirements found.; при ошибке запишите точную пару библиотек и её ограничения. Не обновляйте вслепую все пакеты, пока проект уже содержит конфликт.Linux · Терминал (Bash)КомандаПроверка без модификации окружения; сообщает только конфликты метаданных.python -m pip check
- Проведите обновление сначала в копииСоздайте новое
.venv-test, установите требуемые версии и прогоните тесты. При наличии современных pip можно использовать--dry-run -r requirements.txtдля предварительного плана, но он не гарантирует работоспособность приложения. Сохраните новый перечень версий, только затем согласуйте обновление в работе.
- Сохраните контрольную точку откатаВместе с before-upgrade.txt сохраните данные о версии Python, ОС, архитектуре, файлах приложения и способе запуска. Если тесты провалились, вернитесь к предыдущему окружению/конфигурации, а не пытайтесь заново угадать версии.
#Проверка результата и действия при неуспехе
Есть три артефакта: версия и путь Python, снимок пакетов, результат pip check. На тестовой среде после обновления проходят основные сценарии проекта.
Если исправление не помогло, вернитесь к точному сообщению об ошибке, сохраните версию Python, адрес целевого окружения и очищенный от секретов журнал; выясните, на каком шаге результат отличается от ожидаемого. Не изменяйте глобальный Python ради устранения сбоя проекта.