Окружение

venv, зависимости и «у меня работает»

Что это

Окружение — набор библиотек, с которыми запускается проект. Если у тебя и на сервере они разные, код будет вести себя по-разному, и причину этого найти трудно: сам код одинаковый.

Для работы с ИИ окружение важно ещё и потому, что это единственный способ назвать версии — а версия решает больше, чем кажется (статья 2.11).

Как выглядит в коде

Виртуальное окружение

python3 -m venv .venv                      # создать
source .venv/bin/activate                  # включить (Linux, macOS)
.venv\Scripts\activate                     # включить (Windows)
pip install -r requirements.txt            # поставить зависимости

.venv — папка с библиотеками этого проекта. Без неё пакеты ставятся системно, проекты начинают конфликтовать, и в какой-то момент обновление для одного ломает другой.

Признак, что окружение включено: в начале строки терминала появляется (.venv).

Зафиксировать то, что стоит

pip freeze > requirements.txt

aiogram==3.13.1
aiohttp==3.9.5
certifi==2026.7.22

Теперь на сервере pip install -r requirements.txt поставит ровно те же версии.

Узнать версию перед запросом

pip freeze | grep aiogram

aiogram==3.13.1

Одна команда — и причина 3 из статьи 3.1 закрыта.

Что не должно попадать в git

.venv/
__pycache__/
*.db
.env

Папка .venv весит сотни мегабайт и содержит чужой код — в репозитории ей нечего делать. Список зависимостей для этого и нужен.

Как сказать ИИ

Вот мой requirements.txt. Пиши код только под эти версии,
новых зависимостей не добавляй.

<содержимое>

При странных ошибках:

Код падает с ImportError: cannot import name 'Dispatcher'.
pip freeze показывает aiogram==3.13.1. Под какую версию
написан этот код?

Перед добавлением библиотеки:

Можно решить это стандартной библиотекой, без новой
зависимости? Если нет — объясни, почему, и скажи,
насколько эта библиотека живая.

Другие стеки

Принцип одинаковый везде, меняются только имена файлов:

Файлы с lock в имени фиксируют точные версии — их коммитят, а папки с библиотеками не коммитят никогда.

На что смотреть

Пакеты ставятся без окружения. Признак: pip install работает, а (.venv) в строке терминала нет.

requirements.txt не обновлён. Поставил библиотеку, забыл зафиксировать — на сервере проект не запустится.

Версии без ==. aiogram без номера означает «любая, в том числе та, что выйдет завтра и всё сломает».

.venv в репозитории. Проверяется одной командой: git status --short после создания окружения. Если .venv виден — его нет в .gitignore.

Разные версии Python. У тебя 3.12, на сервере 3.9 — и синтаксис list[str] | None там не работает. Версию языка тоже стоит сверять.

Шпаргалка