Wed Aug 6th, 2025 — 78 days ago

Why a Python Virtual Environment Is Essential for Modern Python Development

Problem

Python projects often require different versions of packages, which can conflict if installed globally.
Installing or updating Python packages system-wide can break other projects or even the OS Python install.
Developers need a way to isolate project dependencies and manage them cleanly per-project.

Solutions

Create one virtual environment per project to isolate packages, tools, and interpreter settings. Activate it in your shell, install requirements inside it, and commit only a lock file (e.g., requirements.txt), not the environment itself.

Create Venv Python Linux or macOS

python3 -m venv .venv
source .venv/bin/activate

Verify you’re inside the venv:

which python
python -c "import sys; print(sys.executable); print(sys.prefix)"

Python Venv Windows (PowerShell)

py -3 -m venv .venv
.venv\Scripts\Activate.ps1

Verification:

Get-Command python | Select-Object -ExpandProperty Source
python -c "import sys; print(sys.executable); print(sys.prefix)"

Python Venv Windows (CMD)

py -3 -m venv .venv
.venv\Scripts\activate.bat

Installing Packages Inside a Venv

Always use the interpreter’s pip so you don’t install to system Python:

python -m pip install -U pip
python -m pip install requests fastapi uvicorn

Using requirements.txt

Capture your environment:

python -m pip freeze > requirements.txt

Recreate it elsewhere:

python -m venv .venv
source .venv/bin/activate   # or Windows activation
python -m pip install -r requirements.txt

Deactivating a Venv

Leave the environment at any time:

deactivate

Where Venv Files Live

A .venv/ directory is created inside your project:

.project-root/
  .venv/
    bin/                      # POSIX scripts (python, pip, activate)
    Scripts/                  # Windows scripts (python.exe, pip.exe)
    lib/pythonX.Y/site-packages/   # POSIX installed packages
    Lib/site-packages/             # Windows installed packages

Safely Removing a Venv

Delete the folder directly after deactivating:

# POSIX
deactivate || true
rm -rf .venv

# Windows PowerShell
Remove-Item -Recurse -Force .venv

Things to Consider

Activate the venv in every new shell session before running tools or installs.
Do not commit .venv/ to version control; add it to .gitignore.
Each project should have its own venv; keep them small and disposable.
IDEs (VS Code, PyCharm) auto-detect venvs and can select .venv/bin/python (or .\.venv\Scripts\python.exe on Windows).
To target a specific Python version:
- python3.12 -m venv .venv (POSIX), or py -3.12 -m venv .venv (Windows).
If Activate.ps1 is blocked on Windows, allow scripts for the current user:
- Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
For global CLI tools, consider pipx instead of installing into a project venv.

Gotchas

Forgetting to activate the venv and accidentally installing to system Python.
Mixing pip and python -m pip; use python -m pip to hit the right interpreter.
Running sudo pip install ...; this pollutes system Python and can break OS tools.
Deleting the venv while it’s still active in a shell; always deactivate first.
Pinning nothing in requirements.txt; use pip freeze so teammates can reproduce the environment.
Committing .venv/ to Git; it’s large, machine-specific, and unnecessary.

Sources

Further Investigation

Explore pip-tools, pipenv, poetry, or conda if you need lock files, extras, or environments beyond venv.
Learn how site-packages resolution and sys.path work inside a venv.
Consider Docker for full system isolation when native dependencies are complex.

TL;DR

Create a venv per project, activate it, install with python -m pip, freeze to requirements.txt, and keep .venv/ out of Git.

python3 -m venv .venv && \
  source .venv/bin/activate && \
  python -m pip install -U pip && \
  python -m pip install -r requirements.txt