Python Venv Management

Python Virtual Environment Management

⚠️ Repo Reality Check (read this first)

The repo's startup scripts are inconsistent:

• dev-start.sh activates .venv/bin/activate (the canonical name).
• run.sh activates venv/bin/activate (legacy).

Standardise on .venv/. When invoking Python or pip in this workspace, prefix with .venv/bin/python / .venv/bin/pip (or activate first). Tests are run via .venv/bin/python -m pytest (pytest.ini).

Local Python should be 3.11+ to match the Dockerfile runtime; some transformers / torch deprecation filters in pytest.ini assume modern versions.

Core Principle

ALWAYS use the project's .venv when running Python commands in the terminal. NEVER run Python commands without first activating or using the virtual environment.

Critical Rules

1. Check for .venv first - Always verify .venv exists before running Python commands
2. Use activation commands - Activate .venv in every terminal session
3. Shell-aware - Detect shell type (Bash, Zsh, PowerShell) and use appropriate commands
4. No global Python - Never use system Python when .venv exists
5. Fail fast - If .venv doesn't exist, create it or fail clearly
6. macOS default - Prefer Bash/Zsh patterns on macOS

Shell Detection & Commands

macOS Terminal (Zsh - Default)

# Activate .venv
source .venv/bin/activate

# Run Python commands
python app.py
pip install -r requirements.txt

# Check if activated
echo $VIRTUAL_ENV                 # Should show .venv path

# Direct execution (no activation needed)
.venv/bin/python app.py
.venv/bin/pip install package

macOS PowerShell

# Activate .venv
./.venv/bin/Activate.ps1

# Run Python commands
python -m <module>
pip install <package>

# Check if activated
$env:VIRTUAL_ENV                  # Should show .venv path

Linux Bash

# Activate .venv
source .venv/bin/activate

# Run Python commands
python app.py
pip install -r requirements.txt

# Check if activated
echo $VIRTUAL_ENV                 # Should show .venv path

Windows PowerShell

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

# Run Python commands
python -m <module>
pip install <package>

# Check if activated
$env:VIRTUAL_ENV                  # Should show .venv path

Windows Command Prompt

# Activate .venv
.venv\Scripts\activate.bat

# Run Python commands
python app.py
pip install -r requirements.txt

Command Patterns

Pattern 1: Direct Execution (PREFERRED - No activation needed)

# macOS/Linux - Most reliable method
.venv/bin/python app.py
.venv/bin/python -m flask run
.venv/bin/pip install package

# PowerShell
./.venv/bin/python app.py
./.venv/bin/python -m flask run

Pattern 2: Activation + Command (macOS Zsh)

source .venv/bin/activate && python app.py

Pattern 3: Activation + Command (PowerShell)

./.venv/bin/Activate.ps1 ; python app.py

OS-Specific Paths

Implementation Checklist

Before running ANY Python command, verify:

• Is this a Python project? (Check for .venv, requirements.txt, *.py files)
• Does .venv exist? (Check for .venv directory)
• What shell am I using? (PowerShell vs Bash/Zsh)
• Am I using the correct activation syntax?
• Can I use direct .venv/bin/python instead of activating?

Standard Workflows

Workflow 1: Running Python Scripts

PowerShell:

# Method 1: Activate then run
./.venv/bin/Activate.ps1 ; python app.py

# Method 2: Direct execution (PREFERRED)
./.venv/bin/python app.py

Bash:

# Method 1: Activate then run
source .venv/bin/activate && python app.py

# Method 2: Direct execution (PREFERRED)
.venv/bin/python app.py

Workflow 2: Installing Packages

PowerShell:

./.venv/bin/Activate.ps1 ; pip install <package>
# OR
./.venv/bin/python -m pip install <package>

Bash:

source .venv/bin/activate && pip install <package>
# OR
.venv/bin/python -m pip install <package>

Workflow 3: Running Flask/Django

PowerShell:

./.venv/bin/Activate.ps1 ; python app.py
# OR
./.venv/bin/python app.py

Bash:

source .venv/bin/activate && python app.py
# OR
.venv/bin/python app.py

Virtual Environment Setup

Check if .venv Exists

# PowerShell
Test-Path .venv

# Bash
test -d .venv && echo "exists" || echo "missing"

Create .venv if Missing

# PowerShell
python -m venv .venv

# Bash
python3 -m venv .venv

Verify Activation

# PowerShell - Should show .venv path
$env:VIRTUAL_ENV

# Bash - Should show .venv path
echo $VIRTUAL_ENV

Common Errors & Solutions

Error: "Activate.ps1 cannot be loaded"

Solution: Set PowerShell execution policy

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Error: "python: command not found"

Solution: Use python3 or direct .venv path

# Use python3
python3 -m venv .venv

# Or use .venv directly
./.venv/bin/python app.py

Error: "No module named 'flask'"

Solution: Ensure .venv is activated and packages installed

./.venv/bin/Activate.ps1 ; pip install -r requirements.txt

Best Practices

1. Always use .venv/bin/python directly - Most reliable method
2. Never assume system Python - Always check for .venv
3. Detect shell type - Use appropriate activation syntax
4. Fail gracefully - If .venv missing, create it first
5. Document requirements - Keep requirements.txt updated
6. Use python -m - More reliable than calling pip/flask directly

Terminal Command Template

Use this template for ALL Python-related terminal commands:

# Step 1: Detect shell
shell_type = "powershell" if on_windows or using_pwsh else "bash"

# Step 2: Check .venv exists
if not exists(".venv"):
    create_venv()

# Step 3: Build command with activation
if shell_type == "powershell":
    command = "./.venv/bin/Activate.ps1 ; <your_command>"
else:
    command = "source .venv/bin/activate && <your_command>"

# Step 4: Execute
run_in_terminal(command)

Quick Reference

Integration with Other Skills

• git-workflow-management: Activate .venv before running git hooks with Python
• code-documentation-standards: Ensure .venv active when generating docs
• ai-training-data-generation: Activate .venv before training scripts

Example Commands

Starting Flask App

# PowerShell (PREFERRED)
./.venv/bin/python app.py

# Or with activation
./.venv/bin/Activate.ps1 ; python app.py

Installing Requirements

# PowerShell (PREFERRED)
./.venv/bin/python -m pip install -r requirements.txt

# Or with activation
./.venv/bin/Activate.ps1 ; pip install -r requirements.txt

Running Tests

# PowerShell (PREFERRED)
./.venv/bin/python -m pytest tests/

# Or with activation
./.venv/bin/Activate.ps1 ; pytest tests/

Multiple Commands

# PowerShell
./.venv/bin/Activate.ps1 ; pip install flask ; python app.py

# Bash
source .venv/bin/activate && pip install flask && python app.py

Validation

Before completing any Python task, verify:

1. ✅ .venv exists in project root
2. ✅ Correct shell syntax used (PowerShell vs Bash)
3. ✅ Virtual environment activated in command
4. ✅ No system Python used accidentally
5. ✅ Command tested and working

Time Savings

Using this skill saves time by:

• ❌ No more "python: command not found" errors
• ❌ No more "No module named X" errors
• ❌ No more debugging which Python is running
• ✅ Consistent environment every time
• ✅ One command that always works
• ✅ No manual activation needed

Remember

The most important rule: If you're running Python code, you MUST use .venv. No exceptions.