Python Venv

Python Virtual Environment Requirement

Core Rule

Use virtual environment when installing packages or running scripts that require third-party dependencies.

When Virtual Environment is REQUIRED

When Virtual Environment is NOT Required

Python Standard Library (No venv needed)

These modules are built-in and don't require virtual environment:

os, sys, json, re, math, datetime, pathlib, subprocess, 
collections, itertools, functools, argparse, logging,
urllib, http, socket, threading, multiprocessing, etc.

Workflow (When venv IS Required)

1. Check if virtual environment exists (.venv, venv, env, .env) → If YES, activate and reuse it
2. If NOT exists → Create with uv (if available) or python3 -m venv
3. Activate, then proceed with Python commands

Detecting Existing Virtual Environment

Check in this order (first match wins):

# Common virtual environment directory names
.venv/  →  Most common (preferred)
venv/   →  Also common
env/    →  Sometimes used
.env/   →  Less common (be careful: may conflict with dotenv files)

Setup Methods

Option 1: uv (Recommended - Faster)

# Create virtual environment
uv venv

# Activate (Linux/macOS)
source .venv/bin/activate

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

# Activate (Windows CMD)
.venv\Scripts\activate.bat

# Install packages
uv pip install <package>

Option 2: Standard venv (Fallback if uv not installed)

# Create virtual environment
python3 -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

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

# Activate (Windows CMD)
.venv\Scripts\activate.bat

# Install packages
pip install <package>

Option 3: Conda/Mamba

# Create environment
conda create -n myenv python=3.11

# Activate
conda activate myenv

# Install packages
conda install <package>
# or
pip install <package>

Workflow Checklist

Before Python operations requiring venv:

1. Check for existing virtual environment (in order): .venv/, venv/, env/, .env/
2. Also check for conda: conda info --envs or check if CONDA_PREFIX is set
3. If exists → Reuse it (activate the found environment)
4. If not exists → Create: uv venv (preferred) or python3 -m venv .venv (fallback)
5. Activate and proceed

Priority: Always reuse existing virtual environment to preserve installed packages.

Quick Reference

Common Patterns

Standard Pattern (Linux/macOS) - Reuse or Create with Fallback

# Find existing venv or create new one (uv with fallback to venv)
if [ -d .venv ]; then
    source .venv/bin/activate
elif [ -d venv ]; then
    source venv/bin/activate
elif [ -d env ]; then
    source env/bin/activate
elif command -v uv &> /dev/null; then
    uv venv && source .venv/bin/activate
else
    python3 -m venv .venv && source .venv/bin/activate
fi

One-liner (Linux/macOS)

# Quick version: check .venv, fallback to create
[ -d .venv ] && source .venv/bin/activate || { command -v uv &>/dev/null && uv venv || python3 -m venv .venv; source .venv/bin/activate; }

Windows PowerShell

# Find existing venv or create new one
if (Test-Path .venv) { .\.venv\Scripts\Activate.ps1 }
elseif (Test-Path venv) { .\venv\Scripts\Activate.ps1 }
elseif (Get-Command uv -ErrorAction SilentlyContinue) { uv venv; .\.venv\Scripts\Activate.ps1 }
else { python -m venv .venv; .\.venv\Scripts\Activate.ps1 }

Running a Python Script

# Activate existing or create new
[ -d .venv ] && source .venv/bin/activate || { command -v uv &>/dev/null && uv venv || python3 -m venv .venv; source .venv/bin/activate; }

# Install dependencies (check both requirements.txt and pyproject.toml)
[ -f requirements.txt ] && pip install -r requirements.txt
[ -f pyproject.toml ] && pip install -e .

# Run script
python script.py

Check if venv is Active

# Should show path containing .venv, venv, or env
which python

# Or check VIRTUAL_ENV environment variable
echo $VIRTUAL_ENV

Check if Conda Environment is Active

# Check CONDA_PREFIX
echo $CONDA_PREFIX

# List all conda environments
conda info --envs

Forbidden Actions

• Using pip install with system Python (always use venv)
• Installing packages globally
• Assuming third-party packages are available without explicit installation
• Overwriting existing virtual environment without checking first

Allowed Without venv

• python3 -c "print('hello')"
• python3 -c "import os; print(os.getcwd())"
• python3 --version
• Any stdlib-only one-liner

Project Type Detection

Troubleshooting

Corrupted Virtual Environment

If venv is broken (import errors, missing packages after install):

# Remove and recreate
rm -rf .venv
uv venv && source .venv/bin/activate
# or
python3 -m venv .venv && source .venv/bin/activate

Wrong Python Version

# Specify Python version with uv
uv venv --python 3.11

# Or with standard venv
python3.11 -m venv .venv

Permission Denied on Windows

Run PowerShell as Administrator, or:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

WSL (Windows Subsystem for Linux)

Use Linux commands in WSL:

# Same as Linux/macOS
source .venv/bin/activate

Note: Don't mix Windows venv with WSL. Create separate venv for each environment.