venv-manager

jmagly's avatarfrom jmagly

Create, manage, and validate Python virtual environments. Use for project isolation and dependency management.

⭐51stars🔀4forks📁View on GitHub🕐Updated Jan 4, 2026⬇️4downloads

When & Why to Use This Skill

The venv-manager skill is a specialized utility designed to automate the lifecycle of Python virtual environments. It ensures project isolation and robust dependency management by handling environment creation, package installation via pip, and state validation. By implementing grounding checks and recovery protocols, it minimizes configuration errors and streamlines the setup process for Python-based software development.

Use Cases

  • Project Initialization: Automatically setting up isolated Python environments (venv/.venv) for new repositories to prevent global dependency conflicts.
  • Dependency Management: Streamlining the installation of packages from requirements.txt or pyproject.toml and generating lock files for environment reproducibility.
  • Environment Validation & Troubleshooting: Performing health checks to identify missing dependencies or version mismatches and executing recovery protocols to repair corrupted environments.
  • Multi-Version Python Support: Managing environments across different Python versions (e.g., 3.11 vs 3.12) to ensure compatibility with specific project requirements.
namevenv-manager
descriptionCreate, manage, and validate Python virtual environments. Use for project isolation and dependency management.
toolsRead, Write, Bash

Virtual Environment Manager Skill

Purpose

Single responsibility: Create and manage Python virtual environments for project isolation. (BP-4)

Grounding Checkpoint (Archetype 1 Mitigation)

Before executing, VERIFY:

  • Python interpreter available and version known
  • Target directory exists and is writable
  • No conflicting venv already active
  • requirements.txt or pyproject.toml exists (for install)

DO NOT create venv without confirming Python version.

Uncertainty Escalation (Archetype 2 Mitigation)

ASK USER instead of guessing when:

  • Multiple Python versions available - which to use?
  • Existing venv found - replace or use?
  • requirements.txt vs pyproject.toml both present
  • Development vs production dependencies

NEVER delete existing venv without confirmation.

Context Scope (Archetype 3 Mitigation)

Context Type Included Excluded
RELEVANT Python version, project deps, venv path Application code
PERIPHERAL CI/CD requirements Test configurations
DISTRACTOR Deployment configs Other language envs

Workflow Steps

Step 1: Check Python Environment (Grounding)

# Available Python versions
which python3
python3 --version

# Check for existing venv
ls -la venv/ 2>/dev/null || ls -la .venv/ 2>/dev/null || echo "No venv found"

# Current active environment
echo "VIRTUAL_ENV: $VIRTUAL_ENV"

Step 2: Create Virtual Environment

# Standard creation
python3 -m venv venv

# With specific Python version
python3.11 -m venv venv

# With system packages access
python3 -m venv venv --system-site-packages

# Verify creation
ls -la venv/bin/python

Step 3: Activate and Install Dependencies

# Activate
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install from requirements.txt
pip install -r requirements.txt

# Or from pyproject.toml
pip install -e .

# Development dependencies
pip install -r requirements-dev.txt

Step 4: Validate Environment

# List installed packages
pip list

# Check for missing deps
pip check

# Export current state
pip freeze > requirements-lock.txt

Recovery Protocol (Archetype 4 Mitigation)

On error:

  1. PAUSE - Don't delete corrupted venv
  2. DIAGNOSE - Check error type:
    • venv creation failed → Check Python installation
    • pip install failed → Check network, package availability
    • activation failed → Check shell compatibility
    • dependency conflict → Use pip-tools or poetry
  3. ADAPT - Try alternative approach (rebuild, different Python)
  4. RETRY - With fresh venv (max 3 attempts)
  5. ESCALATE - Report with pip debug info

Rollback command:

rm -rf venv && python3 -m venv venv

Checkpoint Support

State saved to: .aiwg/working/checkpoints/venv-manager/

checkpoints/venv-manager/
├── python_version.txt       # Python used
├── pip_freeze.txt           # Installed packages
├── creation_log.txt         # Creation output
└── validation_status.json   # Health check results

Common Commands

Command Purpose
python3 -m venv venv Create venv
source venv/bin/activate Activate (bash/zsh)
venv\Scripts\activate Activate (Windows)
deactivate Deactivate
pip freeze > requirements.txt Export deps
pip install -r requirements.txt Install deps

Best Practices

  1. Naming: Use venv/ or .venv/ consistently
  2. Git: Add venv to .gitignore
  3. Lock files: Use pip freeze or pip-tools
  4. Isolation: Always create project-specific venvs
  5. Documentation: Document Python version in README

References