The environment

venv, dependencies and "it works on my machine"

What it is

The environment is the set of libraries a project runs with. If yours and the server's differ, the code behaves differently, and the reason is hard to find: the code itself is identical.

For working with an AI the environment matters for another reason too: it is the only way to name the versions — and the version decides more than it seems (article 2.11).

What it looks like in code

A virtual environment

python3 -m venv .venv                      # create
source .venv/bin/activate                  # activate (Linux, macOS)
.venv\Scripts\activate                     # activate (Windows)
pip install -r requirements.txt            # install the dependencies

.venv is the folder with this project's libraries. Without it packages are installed system-wide, projects start conflicting, and at some point an update for one breaks another.

The sign that the environment is active: (.venv) appears at the start of the terminal line.

Pinning what is installed

pip freeze > requirements.txt

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

Now pip install -r requirements.txt on the server installs exactly the same versions.

Finding the version before a prompt

pip freeze | grep aiogram

aiogram==3.13.1

One command, and reason 3 from article 3.1 is closed.

What must not get into git

.venv/
__pycache__/
*.db
.env

The .venv folder weighs hundreds of megabytes and holds other people's code — it has no business in a repository. That is what the dependency list is for.

What to tell the AI

Here is my requirements.txt. Write code only for these versions,
don't add new dependencies.

<contents>

For strange errors:

The code fails with ImportError: cannot import name 'Dispatcher'.
pip freeze shows aiogram==3.13.1. Which version was this code
written for?

Before adding a library:

Can this be solved with the standard library, without a new
dependency? If not, explain why, and tell me how alive this
library is.

Other stacks

The principle is the same everywhere; only the file names change:

Files with lock in the name pin exact versions — those get committed, while the folders full of libraries never do.

What to look for

Packages installed with no environment. The sign: pip install works and there is no (.venv) in the terminal line.

requirements.txt not updated. You installed a library and forgot to pin it — the project won't start on the server.

Versions without ==. aiogram with no number means "any, including the one released tomorrow that breaks everything".

.venv in the repository. Checked with one command: git status --short after creating the environment. If .venv shows up, it isn't in .gitignore.

Different Python versions. You have 3.12, the server has 3.9 — and the list[str] | None syntax doesn't work there. The language version is worth comparing too, not just the libraries'.

Cheat sheet