Python Environment Setup & Dependency Isolation

1. Why You Must Never Use Global "sudo pip install"

Modern Linux (Ubuntu/Debian) and macOS distributions rely on system Python scripts for internal OS package management and hardware drivers. Installing packages globally with pip install overrides critical system libraries, leading to unrecoverable OS package manager failures (PEP 668 "externally managed environment" error).

2. Using Built-In Virtual Environments (venv)

Python ships with the built-in venv module, requiring zero third-party tools to create an isolated sandbox:

# 1. Create a dedicated virtual environment directory named .venv
python -m venv .venv

# 2. Activate the virtual environment
# On macOS / Linux:
source .venv/bin/activate

# On Windows (PowerShell):
.venv\Scripts\Activate.ps1

# On Windows (Command Prompt):
.venv\Scripts\activate.bat

# 3. Verify that python points to the isolated sandbox
which python  # Output: /path/to/project/.venv/bin/python

# 4. Deactivate when finished
deactivate

3. Managing Dependencies with requirements.txt

To ensure that colleagues and cloud Docker deployment containers run the exact same package versions, export your environment dependencies:

# Install production packages
pip install requests pandas pydantic

# Freeze exact deterministic dependency versions
pip freeze > requirements.txt

# Inspect requirements.txt:
# pydantic==2.8.2
# requests==2.32.3
# pandas==2.2.2

# Replicate the entire environment on a new machine or production server
pip install -r requirements.txt

4. Modern Tooling: Blazing Fast Package Management with UV

Created by Astral (the creators of Ruff), uv is an extremely fast Python package and project manager written in Rust. It serves as a 10-100x faster drop-in replacement for pip, venv, and pip-tools:

# Install uv (via curl or standalone installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment in 10 milliseconds
uv venv

# Install dependencies with parallel Rust resolver & global cache
uv pip install fastapi uvicorn numpy

# Execute Python scripts inside ephemeral environments with auto-installed dependencies
uv run --with httpx script.py

5. Recommended VS Code Developer Configuration

In your project root, create .vscode/settings.json so your IDE automatically selects your virtual environment:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    }
  }
}