Python Project Starter (venv + uv)

Before you start

Check Python is installed (3.10+ is a good floor):

python --version     # Windows
python3 --version    # Mac/Linux

The classic way: venv + pip

mkdir my-project && cd my-project
python -m venv .venv

Activate it — this is the part everyone forgets, and it's per-terminal:

.venv\Scripts\activate        # Windows (PowerShell or cmd)
source .venv/bin/activate     # Mac/Linux

Your prompt now shows (.venv). Install things and record them:

pip install requests
pip freeze > requirements.txt

On another machine (or after deleting .venv): recreate the venv, activate, then pip install -r requirements.txt.

The modern way: uv

uv replaces venv + pip and is dramatically faster. Once uv is installed (one-line installer from astral.sh/uv):

uv init my-project
cd my-project
uv add requests
uv run main.py

That's the whole workflow — uv add manages pyproject.toml and the venv for you, and uv run uses it without manual activation. Starting fresh in 2026, use uv; the venv recipe is here for older projects.

Minimal project layout

my-project/
├── .venv/            # never commit this
├── main.py
├── requirements.txt  # or pyproject.toml with uv
└── .gitignore        # put .venv/ and __pycache__/ in it

Common gotchas

• "pip installs but import fails": your editor or terminal isn't using the venv. In VS Code: Ctrl+Shift+P → "Python: Select Interpreter" → pick .venv.
• Activation "not digitally signed" error (Windows PowerShell): run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser once.
• python opens the Microsoft Store: install real Python from python.org and check "Add to PATH", or use py -3.
• Committed the venv by accident: it's machine-specific junk — .gitignore it and rebuild from requirements.