Виртуальное окружение сломалось в Python: девять причин

Вы активировали окружение командой source .venv/bin/activate, но which python показывает /usr/bin/python3. Или pip install падает с bad interpreter: No such file or directory. Или после обновления системы весь проект перестал импортировать пакеты, которые точно были установлены. Всё это — типовые поломки виртуального окружения, и почти каждую можно диагностировать за пару команд.

Ниже — девять причин, отсортированных по частоте. Для каждой: как проверить, что дело именно в ней, и как чинить. Актуально для CPython 3.8–3.13 и модуля venv из стандартной библиотеки. Если вы используете conda — часть пунктов не про вас, там своя логика окружений.

Как понять, что окружение реально активно

Прежде чем чинить, убедитесь, что проблема есть. Три команды, которые дают полную картину:

# путь к текущему интерпретатору
which python        # Linux/macOS
where python        # Windows (cmd)
Get-Command python  # Windows (PowerShell)

# откуда python видит пакеты
python -c "import sys; print(sys.prefix); print(sys.executable)"

# путь до pip
pip -V

Если sys.prefix указывает на папку вашего окружения (например, /home/user/project/.venv) — окружение активно. Если на /usr или C:\Python313 — вы работаете с системным Python, что бы ни писал префикс (.venv) в приглашении терминала.

Девять причин по убыванию частоты

1. Окружение просто не активировано

Самое частое. Приглашение (.venv) в терминале — это переменная PATH, а не гарантия. Новая вкладка терминала, перезапуск IDE, скрипт, запущенный через cron, — активация не наследуется.

Проверка: echo $VIRTUAL_ENV (пусто — окружение не активно). Чиним: source .venv/bin/activate заново. Для скриптов и cron указывайте полный путь к интерпретатору: /path/.venv/bin/python script.py — активация тогда вообще не нужна.

2. Папку с проектом переименовали или переместили

Внутри окружения хранятся абсолютные пути. В .venv/bin/activate прописан полный путь до папки, а shebang в .venv/bin/pip — жёстко зашитый путь к интерпретатору. Переместили проект из ~/dev/shop в ~/projects/shop — и pip ломается с bad interpreter.

Виртуальное окружение почти никогда не стоит переносить или копировать. Дешевле удалить и создать заново — это секунды плюс переустановка пакетов.

Чиним: удалите папку и пересоздайте. Если пакеты нужно сохранить — сначала снимите список:

# до удаления, если окружение ещё запускается
pip freeze > requirements.txt

# пересоздание
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Системный Python обновили, и окружение осиротело

Классика на macOS с Homebrew и в rolling-дистрибутивах Linux. Окружение при создании ссылается на конкретный бинарник, например /opt/homebrew/bin/python3.11. Обновление Homebrew сносит 3.11, ставит 3.12 — символическая ссылка внутри .venv/bin/python ведёт в никуда.

Проверка: ls -la .venv/bin/python* покажет битую ссылку (в некоторых терминалах — красным). Чиним: только пересоздание на актуальной версии интерпретатора. Скопировать пакеты между разными минорными версиями Python не получится — они лежат в lib/python3.X/ и завязаны на версию.

4. Смешались pip и python из разных мест

Вы вызываете pip install requests, пакет ставится, но import requests падает. Причина: pip в PATH раньше, чем pip из окружения, и он кладёт пакеты в системный site-packages.

Проверка: сравните вывод which pip и which python — они должны быть в одной папке. Чиним: всегда вызывайте pip через интерпретатор — python -m pip install requests. Так пакет гарантированно уйдёт в тот же Python, что и запускается.

5. В окружение просочились системные пакеты

Если окружение создано с флагом --system-site-packages, оно видит глобально установленные пакеты. Иногда это делают случайно, иногда наследуют из старой инструкции. Итог — конфликты версий, которые невозможно объяснить.

Проверка: в .venv/pyvenv.cfg найдите строку include-system-site-packages. Значение true — окружение не изолировано. Чиним: пересоздайте без флага (по умолчанию значение false).

6. PYTHONPATH или PYTHONHOME переопределены

Переменные окружения PYTHONPATH и PYTHONHOME, заданные в .bashrc или .zshrc, перебивают изоляцию venv. PYTHONHOME особенно вреден: он заставляет интерпретатор искать стандартную библиотеку не там.

Проверка: env | grep PYTHON. Чиним: в норме обе переменные должны быть пусты. Уберите их из конфига оболочки — для активации venv они не нужны.

7. Симлинки против копий: --copies и битые ссылки

По умолчанию на Linux/macOS venv создаёт символическую ссылку на системный интерпретатор, а не копию. Если целевой бинарник исчез (см. пункт 3) или окружение переносилось между машинами — ссылка мертва.

Чиним разово: пересоздать. Чтобы не повторялось на нестабильном системном Python — создавайте с копией интерпретатора внутри окружения: python -m venv --copies .venv. Окружение станет тяжелее, но переживёт удаление системного бинарника.

8. Права доступа: окружение создано под другим пользователем

На сервере окружение нередко создают под root, а приложение запускают под www-data. Итог — Permission denied при попытке pip install или дописать что-то в site-packages.

Проверка: ls -la .venv/bin/python — посмотрите владельца. Чиним: создавайте окружение от того же пользователя, под которым работает сервис, либо смените владельца: chown -R www-data:www-data .venv. Не запускайте pip install под sudo в активном venv — это ломает права внутри папки.

9. Файл activate повреждён или обрезан

Редко, но бывает: неудачное копирование, сбой при git-операции (окружение попало в репозиторий и потом частично восстановилось), обрыв диска. source activate отрабатывает без ошибки, но ничего не меняет.

Проверка: откройте .venv/bin/activate — там должна быть функция deactivate и экспорт VIRTUAL_ENV. Пусто или обрезано — файл битый. Чиним: пересоздание. И добавьте .venv/ в .gitignore — окружению не место в репозитории.

Быстрая диагностика: с чего начинать

Почему пересоздание — не признание поражения

Восемь из девяти причин лечатся удалением и пересозданием окружения. Это не костыль. Виртуальное окружение — расходный материал: оно описывается двумя файлами (requirements.txt или pyproject.toml) и восстанавливается за минуту. Тратить час на реанимацию битых симлинков, когда пересоздание занимает секунды, — плохой размен времени.

Держите список зависимостей в репозитории, а саму папку .venv — вне его. Тогда любая из девяти поломок перестаёт быть проблемой: rm -rf .venv && python -m venv .venv && pip install -r requirements.txt — и вы снова в рабочем состоянии.

Что делать дальше

Чтобы поломки не повторялись:

• Фиксируйте зависимости. Минимум — requirements.txt. Для новых проектов посмотрите на инструменты уровня uv или Poetry, которые управляют окружением и лок-файлом за вас.
• Всегда вызывайте pip как python -m pip — это снимает целый класс ошибок из пункта 4.
• Проверьте свой .gitignore: строка .venv/ должна быть там.
• На нестабильном системном Python (Homebrew, rolling-релизы) создавайте окружение с --copies.
• Уберите из конфига оболочки экспорты PYTHONPATH и PYTHONHOME, если они там есть без явной причины.