#Что происходит и когда возникает ошибка
После pip install --upgrade код Python может перестать находить атрибут, метод или прежний аргумент. Это изменение API библиотеки, а не ошибка загрузки pip: сначала нужно определить новый выпуск, затем выбрать миграцию или безопасный откат.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Метод удалён или переименованРазработчик библиотеки изменил программный интерфейс. | AttributeError или неожиданный keyword argument сразу после обновления | Найти руководство по переходу и адаптировать код. |
| Изменились транзитивные зависимостиПри обновлении изменились требуемые зависимости. | pip freeze показывает новую версию не обновлённой вручную библиотеки | Сопоставить версии и ограничения. |
| Разные версии в приложении и терминалеДва процесса импортируют разные установленные выпуски. | В IDE падение, в CLI работает | Проверить sys.executable и module.__file__. |
#Подробная диагностика и исправление
- Зафиксируйте точную несовместимостьСохраните полный traceback:
AttributeError,TypeErrorоб аргументе илиImportErrorуказывают на разные изменения. Запишите название метода, исходную строку, предыдущую рабочую версию из истории проекта и время обновления.
- Проверьте текущий выпуск и средуВ проблемном окружении выполните
pip showи узнайте версию библиотеки. При тестировании из IDE добавьте временно в тестовый код выводsys.executable, чтобы удостовериться, что он использует ту же среду, что и терминал. - Первая команда только чтение; вторая создаёт локальный снимок версийLinux · Терминал (Bash)КомандаПервая команда только чтение; вторая создаёт локальный снимок версий. Не публикуйте файл, если в нём есть приватные адреса.
python -m pip show ИМЯ_ПАКЕТАpython -m pip freeze > after-upgrade.txt
- Найдите конкретное изменение в официальных заметкахОткройте документацию библиотеки, раздел миграции/заметок к версии. Убедитесь, что обсуждаемый метод действительно удалён или изменил параметры. Не подменяйте проблему случайным примером для другого крупного выпуска.
- Сравните предыдущий снимок окруженияЕсли до обновления существовал before-upgrade.txt или lock-файл, сравните версии напрямую. Для отсутствующего снимка используйте историю requirements.txt и журнал развёртывания; не угадывайте предыдущую версию из памяти. При признаках конфликта зависимостей выполните
pip check. - Обычный пользователь; не меняет пакетыLinux · Терминал (Bash)КомандаОбычный пользователь; не меняет пакеты.
python -m pip check
- Безопасно проверьте возврат к последней рабочей версииСоздайте новую тестовую
.venv-rollbackи установите документированный совместимый выпускИМЯ_ПАКЕТА==X.Y.Z(укажите реальную старую версию). Установите также остальные закреплённые зависимости. Если приложение заработало, это подтверждает регрессию версий, но не отменяет необходимость оценки безопасности старого выпуска. - Только новая тестовая среда; X.Y.Z замените подтверждённой версиейLinux · Терминал (Bash)С осторожностьюТолько новая тестовая среда; X.Y.Z замените подтверждённой версией. Старый релиз может иметь уязвимости.
python -m pip install "ИМЯ_ПАКЕТА==X.Y.Z"Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- Выберите миграцию с тестами или временный откатЕсли есть документированный новый API, измените обращения к методам в ветке разработки и проверьте тесты. Если обновление критично для безопасности, отдайте приоритет адаптации; если нужен временный откат, документируйте причину, ограничьте срок и согласуйте уязвимости.
- Подтвердите приложение, а не только импортЗапустите наиболее важные пользовательские сценарии и тесты с новой версией. Закрепите подтверждённый набор зависимостей в проектном файле и на следующем развёртывании используйте его. Если ошибка возвращается, сравните фактические версии внутри процесса.
#Проверка результата и действия при неуспехе
Исправленный код выполняет прежний сценарий, тесты проходят, фактическая версия в рабочем процессе совпадает с закреплённой.
Если исправление не помогло, вернитесь к точному сообщению об ошибке, сохраните версию Python, адрес целевого окружения и очищенный от секретов журнал; выясните, на каком шаге результат отличается от ожидаемого. Не изменяйте глобальный Python ради устранения сбоя проекта.