setup-venv.md

Virtual Environment Setup with venvman

When setting up Python virtual environments for projects, use the venvman system:

Workflow:

1. Check for existing virtual environment:

   • Look for .venv, venv, env, or other virtual environment directories/symlinks
   • If found, STOP and ask the user:
     • "I found an existing virtual environment. Would you like to:
       • (A) Use the existing environment
       • (B) Delete it and create a new one with venvman"
   • If user chooses (A), work with existing environment (activate and proceed)
   • If user chooses (B), remove the old environment and continue with venvman setup

2. Check for requirements.txt in the project directory

3. If requirements.txt is missing:

   • Analyze the project code to identify imported packages
   • Check for alternative dependency files (pyproject.toml, setup.py, Pipfile)
   • Generate requirements.txt with appropriate versions
   • Strategies to use:
     • Scan .py files for import statements
     • Use pipreqs if available: pipreqs --force .
     • For known packages, specify reasonable version constraints (e.g., flask>=2.0,<3.0)
     • Include common dependencies based on project type (web app, data science, etc.)
   • Save the generated requirements.txt to the project directory

4. Create environment with venvman:

   venvman create --project <project-name> --dir <project-path> --python <version> --install-deps

   • Use a descriptive project name (lowercase, hyphens for spaces)
   • Specify Python version if requirements demand it (default: latest available)
   • Always use --install-deps flag after requirements.txt exists

5. Verify setup:

   • Confirm .venv symlink created
   • Confirm activate.sh generated
   • Activate with: source activate.sh

Note: venvman stores all environments centrally in ~/VirtualEnvironments/ and uses symlinks for IDE compatibility.