Skip to main content

Best Practices for Managing Python Environments

One owner and one purpose​

Give each project an environment and decide which tool owns it (venv/pip, Conda, or another documented workflow). Avoid mixing system packages, user-site installs, and environment-local packages unless the tool's documentation explicitly supports that combination.

Record enough to recreate​

Record:

  • the supported Python major/minor versions;
  • direct dependencies and justified constraints;
  • development-only tools separately from runtime dependencies;
  • non-Python system dependencies that installation requires;
  • the commands used to create and validate the environment.

An environment directory is generated state. Do not commit it or rely on copying it between machines.

Verify instead of guessing​

python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip check

These commands confirm interpreter selection and package metadata consistency. They do not replace application tests.

Resolve conflicts with evidence​

When installation fails:

  1. Read the resolver's conflicting requirements.
  2. Confirm the package and Python versions the project supports.
  3. Adjust direct constraints only when compatibility evidence supports the change.
  4. Recreate a clean environment and run tests.

Do not repeatedly upgrade random packages in a long-lived environment. A clean reconstruction distinguishes incomplete dependency declarations from residue left by earlier experiments.

Keep secrets and notebooks in mind​

Environment variables and credential files are not isolated by a Python virtual environment. Keep secrets out of repositories and notebooks. In Jupyter, confirm that the selected kernel points to the intended environment before installing or importing packages.