Python Virtual Environments

A virtual environment is a self-contained directory that contains a Python installation for a particular version of Python, plus several additional packages. This allows you to manage dependencies for different projects separately, avoiding conflicts and ensuring that each project has access to the specific versions of packages it needs. It keeps your system Python clean and your project reproducible.

---

Quick Start

Pick your platform/shell and run these in your project folder.

Windows (PowerShell)

# create
python -m venv .venv

# activate
.\.venv\Scripts\Activate.ps1

# install packages
python -m pip install --upgrade pip
python -m pip install -r requirements.txt  # if you have one

# deactivate when done
deactivate

Windows (Command Prompt)

python -m venv .venv
.\.venv\Scripts\activate.bat
python -m pip install --upgrade pip
deactivate

macOS/Linux (bash or zsh)

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
deactivate

macOS/Linux (fish)

python -m venv .venv
source .venv/bin/activate.fish
python -m pip install --upgrade pip
deactivate

Tip: Add .venv/ to your .gitignore so you don’t commit the environment.

---

Everyday Use

# upgrade pip inside the env
python -m pip install --upgrade pip

# install a package
python -m pip install requests

# record exact versions
python -m pip freeze > requirements.txt

# install from a lock file
python -m pip install -r requirements.txt

Recreate the environment at any time by deleting .venv/ and running the create + install steps again.

---

VS Code Tips

• Use the command palette → “Python: Select Interpreter” and pick .venv.
• VS Code auto‑detects .venv in the workspace root. If not, set python.defaultInterpreterPath to .venv’s Python.

---

Alternatives (Optional)

• Poetry: dependency management + venvs via poetry add, poetry install.
• Pipenv: pipenv install, pipenv shell.

These are great for larger projects but venv + pip is simple and built‑in.

---

Troubleshooting

• PowerShell says activation is disabled:
  • Temporary (current session): Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
  • Safer long‑term (current user): Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
• python not found:
  • Install Python from python.org or your package manager. On Windows, prefer the official installer and ensure “Add python.exe to PATH” or use the python launcher.
• pip installs globally instead of into the venv:
  • Make sure the env is active, or prefix with python -m pip ....
• Activation script not found after creating venv:
  • Ensure you ran venv with the right interpreter (python -m venv .venv). Delete .venv/ and recreate.

---

FAQ

• Where should I put the venv?
  • Inside the project folder as .venv/ so tools can auto‑detect it.
• Can I have multiple envs per project?
  • Yes. Name them differently (e.g., .venv-3.12, .venv-3.13).
• Is conda the same thing?
  • Similar purpose, different toolchain focused on scientific stacks. These instructions cover the standard library venv.

---

Happy hacking!