Python Venv Manager

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

1. 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

1. Project Setup:

• Initialize new Python projects
• Configure project structure
• Set up testing frameworks
• Configure linting and formatting
• Create reproducible environments

1. Troubleshooting:

• Fix import errors
• Resolve version conflicts
• Debug installation issues
• Handle platform-specific dependencies
• Clean corrupted environments

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

Virtual Environment Tools Comparison

venv (Built-in)

# 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)

# 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)

# 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

# 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)

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

# 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
• Source: CuriousLearner/devkit
• License: MIT

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