Environment Isolation

The rule

Everything installs into an environment that belongs to this project.

python -m venv .venv && .venv/bin/pip install numpy
# or
conda create --prefix ./.conda_env python=3.11 && ./.conda_env/bin/pip install numpy

Never conda activate some-shared-env && pip install .... Never sudo pip. Never install into the interpreter that runs your tooling.

Why this is stricter than it sounds

A research agent working on an econometrics paper needed two libraries. It ran, reasonably enough:

conda activate ark-base && pip install pyblp otree

ark-base was the shared environment that the whole platform ran on. One of those packages pins sqlalchemy==1.3, so pip downgraded it. That broke the database layer for every user of that machine. Nothing crashed loudly. Status reporting simply stopped working, and it took five days and an unrelated investigation to find.

Three minutes later the same agent, unprompted, created a project-local environment and installed the packages again, correctly. The mistake was the first reflex, not the plan.

Consequences worth knowing

Version pins are contagious. Installing a package that pins an old dependency silently downgrades it for everything else in that environment.

Failures are silent. The broken thing is usually not the thing you installed. It is some other component that imported the downgraded library and now takes a different code path, or fails in a try/except that was written for a different reason.

Shared machines have other people on them. In a lab or on a cluster, the environment you are about to modify is someone's running job.

Practical setup

At the start of a project:

python -m venv .venv
.venv/bin/pip install -r requirements.txt

Then use the explicit interpreter path in every command, rather than relying on activation state that a subshell may not inherit:

.venv/bin/python experiment.py

Record what you installed so the paper's environment section is a fact rather than a memory:

.venv/bin/pip freeze > results/environment.txt

If you cannot create a project environment

Say so and stop. Do not fall back to a shared environment because it is available. "I could not create an isolated environment, here is the error" is a fine outcome. Quietly polluting a shared one is not.