# Python Venv Manager

> Python virtual environment management, dependency handling, and project setup automation.

- **Type:** Skill
- **Install:** `agentstack add skill-curiouslearner-devkit-python-venv-manager`
- **Verified:** Pending review
- **Seller:** [CuriousLearner](https://agentstack.voostack.com/s/curiouslearner)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [CuriousLearner](https://github.com/CuriousLearner)
- **Source:** https://github.com/CuriousLearner/devkit/tree/main/skills/python-venv-manager

## Install

```sh
agentstack add skill-curiouslearner-devkit-python-venv-manager
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Python Virtual Environment Manager Skill

Python virtual environment management, dependency handling, and project setup automation.

## Instructions

You are a Python environment and dependency expert. When invoked:

1. **Virtual Environment Management**:
   - Create and configure virtual environments
   - Manage Python versions with pyenv
   - Set up isolated development environments
   - Handle multiple Python versions per project
   - Configure environment activation scripts

2. **Dependency Management**:
   - Generate and manage requirements.txt
   - Use modern tools (pip-tools, poetry, pipenv)
   - Lock dependencies with hashes
   - Handle dev vs production dependencies
   - Resolve dependency conflicts

3. **Project Setup**:
   - Initialize new Python projects
   - Configure project structure
   - Set up testing frameworks
   - Configure linting and formatting
   - Create reproducible environments

4. **Troubleshooting**:
   - Fix import errors
   - Resolve version conflicts
   - Debug installation issues
   - Handle platform-specific dependencies
   - Clean corrupted environments

5. **Best Practices**: Provide guidance on Python packaging, versioning, and environment isolation

## Virtual Environment Tools Comparison

### venv (Built-in)
```bash
# Pros: Built-in, no installation needed
# Cons: Basic features, manual workflow

# Create environment
python3 -m venv venv

# Activate (Linux/Mac)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

# Deactivate
deactivate

# Install dependencies
pip install -r requirements.txt
```

### virtualenv (Enhanced)
```bash
# Pros: More features, faster than venv
# Cons: Requires installation

# Install
pip install virtualenv

# Create with specific Python version
virtualenv -p python3.11 venv

# Create with system site-packages
virtualenv --system-site-packages venv
```

### Poetry (Modern, Recommended)
```bash
# Pros: Dependency resolution, packaging, publishing
# Cons: Learning curve

# Install
curl -sSL https://install.python-poetry.org | python3 -

# Create new project
poetry new my-project

# Initialize existing project
poetry init

# Add dependencies
poetry add requests
poetry add --group dev pytest

# Install dependencies
poetry install

# Run commands in virtual environment
poetry run python script.py
poetry run pytest

# Activate shell
poetry shell

# Update dependencies
poetry update

# Show dependency tree
poetry show --tree
```

### Pipenv
```bash
# Pros: Automatic venv, Pipfile format
# Cons: Slower than alternatives

# Install
pip install pipenv

# Install dependencies
pipenv install requests

# Install dev dependencies
pipenv install --dev pytest

# Activate environment
pipenv shell

# Run command
pipenv run python script.py

# Generate requirements.txt
pipenv requirements > requirements.txt
```

### pyenv (Python Version Manager)
```bash
# Install multiple Python versions
# Manage Python versions per project

# Install
curl https://pyenv.run | bash

# Install Python version
pyenv install 3.11.5
pyenv install 3.12.0

# List available versions
pyenv install --list

# Set global version
pyenv global 3.11.5

# Set local version (per directory)
pyenv local 3.11.5

# List installed versions
pyenv versions

# Show current version
pyenv version
```

## Usage Examples

```
@python-venv-manager
@python-venv-manager --setup-project
@python-venv-manager --create-venv
@python-venv-manager --poetry
@python-venv-manager --fix-dependencies
@python-venv-manager --migrate-to-poetry
```

## Project Setup Workflows

### Basic Project with venv
```bash
# Create project directory
mkdir my-project
cd my-project

# Create virtual environment
python3 -m venv venv

# Activate environment
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install requests pytest black flake8

# Freeze dependencies
pip freeze > requirements.txt

# Create .gitignore
cat > .gitignore > pyproject.toml  requirements.in =4.2,=4.2,=4.2
requests

# requirements-dev.in (development)
-r requirements.in
pytest>=7.4
black>=23.11
flake8>=6.1

# Compile both
pip-compile requirements.in
pip-compile requirements-dev.in
```

## Python Version Management

### Using pyenv
```bash
# Install pyenv
curl https://pyenv.run | bash

# Add to shell configuration (.bashrc, .zshrc)
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

# Install Python versions
pyenv install 3.11.5
pyenv install 3.12.0

# Set global version
pyenv global 3.11.5

# Set local version (creates .python-version file)
pyenv local 3.11.5

# Create virtual environment with specific version
pyenv virtualenv 3.11.5 my-project-env

# Activate virtual environment
pyenv activate my-project-env

# Deactivate
pyenv deactivate

# List virtual environments
pyenv virtualenvs

# Delete virtual environment
pyenv uninstall my-project-env
```

### Using pyenv with Poetry
```bash
# Set local Python version
pyenv local 3.11.5

# Initialize Poetry project
poetry init

# Poetry will use pyenv's Python version
poetry env use python

# Or specify version explicitly
poetry env use 3.11

# List Poetry environments
poetry env list

# Remove environment
poetry env remove python3.11

# Show environment info
poetry env info
```

## Project Structure Best Practices

### Small Project
```
my-project/
├── .gitignore
├── README.md
├── requirements.txt
├── setup.py  (optional)
├── my_module.py
└── tests/
    ├── __init__.py
    └── test_my_module.py
```

### Medium Project
```
my-project/
├── .gitignore
├── README.md
├── pyproject.toml
├── setup.py
├── requirements/
│   ├── base.txt
│   ├── development.txt
│   └── production.txt
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       ├── utils.py
│       └── models.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   └── test_core.py
└── docs/
    └── index.md
```

### Large Project with Poetry
```
my-project/
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
├── poetry.lock
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core/
│       │   ├── __init__.py
│       │   └── engine.py
│       ├── api/
│       │   ├── __init__.py
│       │   └── routes.py
│       └── utils/
│           ├── __init__.py
│           └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── unit/
│   │   └── test_core.py
│   └── integration/
│       └── test_api.py
├── docs/
│   ├── conf.py
│   └── index.rst
└── scripts/
    └── setup_dev.sh
```

## Common Issues & Solutions

### Issue: ModuleNotFoundError
```bash
# Check if virtual environment is activated
which python  # Should point to venv/bin/python

# Verify package is installed
pip list | grep package-name

# Reinstall package
pip install --force-reinstall package-name

# Check Python path
python -c "import sys; print('\n'.join(sys.path))"

# Fix: Activate virtual environment
source venv/bin/activate

# Fix: Install in editable mode for local development
pip install -e .
```

### Issue: Dependency Conflicts
```bash
# Check for conflicts
pip check

# Show dependency tree
pip install pipdeptree
pipdeptree

# Using Poetry (better conflict resolution)
poetry add package-name
# Poetry will resolve conflicts automatically

# Force specific version
pip install "package==1.2.3"

# Use pip-tools to resolve
pip-compile --resolver=backtracking requirements.in
```

### Issue: Multiple Python Versions Confusion
```bash
# Check current Python version
python --version
which python

# Use specific version explicitly
python3.11 -m venv venv

# With pyenv
pyenv versions  # List installed versions
pyenv which python  # Show current python path

# Set specific version for project
pyenv local 3.11.5
```

### Issue: Corrupted Virtual Environment
```bash
# Delete and recreate
rm -rf venv/
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# With Poetry
poetry env remove python3.11
poetry install
```

### Issue: SSL Certificate Errors
```bash
# Temporary workaround (NOT for production)
pip install --trusted-host pypi.org --trusted-host pypi.python.org package-name

# Better solution: Update certificates
pip install --upgrade certifi

# macOS specific
/Applications/Python\ 3.11/Install\ Certificates.command
```

### Issue: Permission Denied
```bash
# Don't use sudo with pip in virtual environment!
# Recreate venv with proper permissions

# Fix ownership
chown -R $USER:$USER venv/

# Use user install only if not in venv
pip install --user package-name
```

## Environment Variables and Configuration

### .env Files
```bash
# Install python-decouple or python-dotenv
poetry add python-dotenv

# Create .env file
cat > .env  .pre-commit-config.yaml ' -f1 | cut -d' requirements.txt

# Pipenv to Poetry
poetry add $(pipenv requirements | sed 's/==/=/g')
```

## Docker Integration

### Dockerfile with Virtual Environment
```dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Copy dependency files
COPY requirements.txt .

# Create virtual environment and install dependencies
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY . .

# Run as non-root
RUN useradd -m -u 1001 appuser && \
    chown -R appuser:appuser /app
USER appuser

CMD ["python", "app.py"]
```

### Dockerfile with Poetry
```dockerfile
FROM python:3.11-slim as builder

WORKDIR /app

# Install Poetry
RUN pip install poetry==1.7.0

# Configure Poetry
ENV POETRY_NO_INTERACTION=1 \
    POETRY_VIRTUALENVS_IN_PROJECT=1 \
    POETRY_VIRTUALENVS_CREATE=1 \
    POETRY_CACHE_DIR=/tmp/poetry_cache

# Copy dependency files
COPY pyproject.toml poetry.lock ./

# Install dependencies
RUN poetry install --without dev --no-root && rm -rf $POETRY_CACHE_DIR

# Runtime stage
FROM python:3.11-slim as runtime

WORKDIR /app

# Copy virtual environment from builder
ENV VIRTUAL_ENV=/app/.venv \
    PATH="/app/.venv/bin:$PATH"
COPY --from=builder /app/.venv ${VIRTUAL_ENV}

# Copy application
COPY . .

# Run as non-root
RUN useradd -m -u 1001 appuser && \
    chown -R appuser:appuser /app
USER appuser

CMD ["python", "app.py"]
```

## Best Practices Summary

### Virtual Environment
- Always use virtual environments (never install globally)
- One virtual environment per project
- Keep venv/ out of version control (.gitignore)
- Document Python version requirements (.python-version)
- Use pyenv for managing multiple Python versions

### Dependency Management
- Pin exact versions in production (no ~, ^)
- Use pip-tools or Poetry for dependency resolution
- Separate dev and production dependencies
- Use lock files (poetry.lock, requirements.txt with hashes)
- Regularly update dependencies for security
- Document why specific versions are pinned

### Project Structure
- Use src/ layout for packages
- Keep tests separate from source
- Include comprehensive .gitignore
- Add README.md with setup instructions
- Use pyproject.toml for modern projects

### Security
- Never commit .env files
- Use python-dotenv for environment variables
- Scan dependencies with pip-audit or safety
- Use hashes in requirements.txt
- Keep dependencies minimal
- Update regularly for security patches

### Development Workflow
- Use pre-commit hooks for code quality
- Configure formatters (black, isort)
- Use type hints and mypy
- Write tests with pytest
- Document setup steps in README

## Quick Reference Commands

```bash
# venv basics
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip freeze > requirements.txt

# Poetry basics
poetry new project
poetry init
poetry add package
poetry install
poetry shell
poetry run python script.py

# pyenv basics
pyenv install 3.11.5
pyenv local 3.11.5
pyenv virtualenv 3.11.5 myenv

# pip-tools basics
pip-compile requirements.in
pip-sync requirements.txt
pip-compile --upgrade

# Common tasks
pip list --outdated
pip check
poetry show --outdated
poetry update
```

## Notes

- Prefer Poetry or pip-tools over manual requirements.txt management
- Use pyenv to manage multiple Python versions
- Always activate virtual environment before installing packages
- Keep dependencies documented and up-to-date
- Use lock files for reproducible builds
- Test dependency updates in isolated environment first
- Configure proper .gitignore to exclude virtual environments
- Use type hints and static analysis tools (mypy)
- Set up CI/CD to verify dependency installation
- Regular security audits of dependencies

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [CuriousLearner](https://github.com/CuriousLearner)
- **Source:** [CuriousLearner/devkit](https://github.com/CuriousLearner/devkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-curiouslearner-devkit-python-venv-manager
- Seller: https://agentstack.voostack.com/s/curiouslearner
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.