venv-manager
Create, manage, and validate Python virtual environments. Use for project isolation and dependency management.
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.
| name | venv-manager |
|---|---|
| description | Create, manage, and validate Python virtual environments. Use for project isolation and dependency management. |
| tools | Read, 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:
- PAUSE - Don't delete corrupted venv
- DIAGNOSE - Check error type:
venv creation failed→ Check Python installationpip install failed→ Check network, package availabilityactivation failed→ Check shell compatibilitydependency conflict→ Use pip-tools or poetry
- ADAPT - Try alternative approach (rebuild, different Python)
- RETRY - With fresh venv (max 3 attempts)
- 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
- Naming: Use
venv/or.venv/consistently - Git: Add venv to
.gitignore - Lock files: Use
pip freezeorpip-tools - Isolation: Always create project-specific venvs
- Documentation: Document Python version in README
References
- Python venv docs: https://docs.python.org/3/library/venv.html
- REF-001: Production-Grade Agentic Workflows (BP-4)
- REF-002: LLM Failure Modes (Archetype 1 grounding)