python-env

Python environments

The environment is part of the project, not scratch space. A user who opens the project tomorrow, or clones it on another machine, should find the environment where their editor, their tooling, and their habits expect it.

Where it goes

Create it inside the project directory — .venv at the project root is the convention nearly every editor and tool auto-detects:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

For a greenfield project, prefer uv, which manages a project-local .venv for you and is much faster:

uv venv
uv pip install -e .      # or `uv sync` when there is a lockfile
uv run python -m yourpkg # runs in the project env without activating

Never put the environment in /tmp, ~/envs, or any other scratch location outside the project. It is invisible to the user's tooling, it is not what they will look for, and on /tmp it is deleted out from under them.

PEP 668: "externally-managed-environment"

Homebrew, Debian, and Ubuntu mark the system interpreter as externally managed, so pip install outside a virtualenv refuses with:

error: externally-managed-environment

That is the signal to create the project environment — not an obstacle to work around. Do not pass --break-system-packages, set PIP_BREAK_SYSTEM_PACKAGES, or delete the EXTERNALLY-MANAGED marker: those mutate an interpreter the OS owns, leave the project with no environment of its own, and can break other software on the machine.

Hand off commands the user can run

Write the run instructions against the project environment, so they work from a fresh shell in the project directory:

source .venv/bin/activate
python -m yourpkg ...

or, with uv, uv run python -m yourpkg ....

Do not hand back absolute paths into an environment outside the project (/tmp/whatever/bin/python -m yourpkg). Even when they work right now, they tell the user their project has no environment of its own.

Respect what is already there

If the project already has an environment or a declared tool — a .venv, a uv.lock, Poetry, Pipenv, conda — use it rather than introducing a second one. Check before creating.