Окружение: venv, версии и воспроизводимость

Почему «у меня работает» — это не результат

Половина потерянного времени в питоне для данных уходит не на код, а на среду, в которой он запускается. Классическая история: скрипт работал в марте, в июле вы его запускаете и получаете ошибку в библиотеке, которую не трогали. Причина почти всегда одна — обновилась версия пакета, а вы её нигде не зафиксировали.

Виртуальное окружение за две минуты

Виртуальное окружение — это отдельная папка с собственным набором пакетов для конкретного проекта. Пакеты одного проекта не мешают другому.

python -m venv .venv
source .venv/bin/activate      # macOS и Linux
.venv\Scripts\activate         # Windows
pip install pandas numpy
pip freeze > requirements.txt

После activate приглашение терминала показывает имя окружения в скобках — это ваш индикатор, что вы не в системном питоне. Строка pip freeze записывает точные версии всего установленного. Именно этот файл делает запуск повторяемым.

Как проверить, где вы находитесь

Когда импорт не находит установленный пакет, дело почти никогда не в пакете. Дело в том, что pip установил его в один питон, а код запускается в другом:

import sys
print(sys.executable)    # какой именно питон выполняет код
print(sys.version)       # версия
import pandas; print(pandas.__version__)

Сравните путь из sys.executable с тем, что выдаёт which python (или where python на Windows). Если пути разные — вы нашли причину. В блокнотах та же проблема выглядит как «в терминале pip install прошёл, в ячейке ModuleNotFoundError»: ядро блокнота смотрит в другое окружение.

Что фиксировать, а что нет

• Версию питона. Запишите её в README проекта одной строкой. Разница между 3.9 и 3.12 иногда ломает синтаксис.
• Версии ключевых библиотек. pandas, numpy и всё, от чего зависит результат расчёта.
• Не фиксируйте папку .venv в гите. Она большая и привязана к вашей машине. В репозиторий идёт requirements.txt, а окружение каждый пересоздаёт у себя.

Восстановление проекта на новой машине

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -c "import pandas; print(pandas.__version__)"

Последняя строка — не формальность, а проверка, что установилось именно то, что ожидалось. Если версия отличается от той, при которой писался код, вы узнаете об этом сейчас, а не посреди расчёта.

Отдельная ловушка — pip install без окружения на системный питон. На macOS и в свежих дистрибутивах это часто заканчивается ошибкой externally-managed-environment. Это не поломка, а защита: система просит вас сделать venv. Не обходите её флагом break-system-packages, потратьте две минуты на окружение.

Шпаргалка

• Один проект — одно виртуальное окружение.
• pip freeze в requirements.txt сразу после установки пакетов.
• ModuleNotFoundError при установленном пакете — почти всегда не тот питон.
• Версия питона и ключевых библиотек — часть описания результата.