#Что произошло и когда проявляется ошибка
После установки новой версии Python библиотека может оказаться несовместимой с новым интерпретатором, отсутствовать в новом окружении или зависеть от бинарного расширения, собранного под прежнюю версию.
#Причины и диагностические признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Пакет в старом интерпретатореПакеты интерпретаторов установлены отдельно. | Старая команда работает, новая выдаёт ModuleNotFoundError | Проверить sys.executable и pip конкретной версии. |
| Расширение несовместимо с новой версиейСкомпилированное расширение или его внешняя зависимость несовместимы. | ImportError или DLL load failed при импорте | Найти подходящий выпуск библиотеки под версию Python. |
| Изменение программного интерфейсаНовая версия зависимости изменила функции и аргументы. | Импорт успешен, но возник AttributeError или TypeError | Сверить журнал изменений пакета, ограничить версии по проекту. |
#Подробная пошаговая диагностика и исправление
- 1. Сохраните сведения о рабочем окруженииВ терминале старой рабочей среды зафиксируйте Python и версии пакетов в файл, который сохраните вместе с проектом. Используйте
python -m pip freezeтолько из проверенного интерпретатора; файлы с приватными URL репозиториев и токенами перед передачей очистите.Linux · Терминал (Bash)КомандаЗапускать из корня тестовой копии проекта; не требует прав администратора.python --versionpython -m pip --versionpython -m pip freeze > requirements-before.txt
- 2. Проверьте новый интерпретатор отдельноВ новом терминале выполните
python -c ...и проверьте значениеsys.executable. Не полагайтесь на внешний вид приглашения. При наличии нескольких Python в Windows пригодитсяpy -0p, в Linux/macOS — явный путь к нужному исполняемому файлу.Linux · Терминал (Bash)КомандаОбычный терминал. Если python указывает на старую версию, используйте явный путь.python -c "import sys; print(sys.version); print(sys.executable)"
- 3. Создайте пробное окружение для новой версииСоздайте новую папку окружения, например
.venv-new, а не пересоздавайте старое. Активируйте его либо используйте исполняемый файл внутри напрямую. Затем установите зависимости из проверенного requirements; не обновляйте все пакеты без плана обратного перехода. - Linux/macOSLinux · Терминал (Bash)КомандаLinux/macOS. Для Windows используйте .venv-new\Scripts\python.exe. Требуется доступ к источнику пакетов.
python -m venv .venv-new./.venv-new/bin/python -m pip install -r requirements-before.txt
- 4. Протестируйте конкретную библиотекуЗапустите импорт и короткую функцию на тестовых входных данных. Если
pipсообщает, что нет совместимого выпуска, ознакомьтесь с поддерживаемыми версиями Python в метаданных пакета. Если ошибкаDLL load failed, проверьте архитектуру и внешние системные библиотеки, не скачивайте DLL с неизвестных сайтов.
- 5. Выберите совместимую комбинацию версийЕсли для нового Python нет поддерживаемого пакета, временно оставьте проект на прежней поддерживаемой среде, отдельно планируйте обновление зависимости. Зафиксируйте удачную комбинацию в файле зависимостей и настройке запуска редактора/службы.
#Как проверить, что проблема устранена
Тестовый импорт и нужная функция библиотеки работают в новой среде; запись о версиях и резервный вариант сохранены.
#Если исправление не помогло
Если обновление невозможно, не переносите виртуальную среду копированием между версиями Python: создавайте новую на целевом интерпретаторе. Возврат к старой версии допустим лишь с учётом её срока поддержки и безопасности.