Python Environment Management Skill

This skill provides tools and workflows for managing Python virtual environments using uv, a fast Python package installer and resolver.

Quick Start

1. Install uv: Ensure uv is installed on your system
2. Create environment: Use uv to create a new virtual environment
3. Install dependencies: Add packages from requirements.txt or pyproject.toml
4. Manage environment: Update, freeze, or clean up dependencies
5. Troubleshoot: Resolve common environment issues

Core Workflow

1. Environment Setup

# Initialize project with uv
uv init project-name
cd project-name

# Create virtual environment
uv venv

# Activate environment
# On Windows:
.venv\Scripts\activate
# On Unix/Mac:
source .venv/bin/activate

2. Dependency Management

# Install packages
uv add package-name
uv add "package-name>=1.0.0"
uv add "package-name[extra]"

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

# Install with development dependencies
uv add --dev pytest black

3. Project Configuration

# Generate requirements.txt
uv pip freeze > requirements.txt

# Sync environment
uv sync

# Update packages
uv update
uv update package-name

uv vs Traditional Tools

Advantages of uv

• Speed: 10-100x faster than pip
• Reliability: Better dependency resolution
• Unified tool: Replaces pip, venv, pip-tools
• Cross-platform: Consistent behavior across systems
• Modern features: Built-in virtual environments, lock files

Command Comparison

Task	uv Command	Traditional Command
Create venv	uv venv	python -m venv .venv
Install package	uv add package	pip install package
Install dev package	uv add --dev package	pip install package
Freeze deps	uv pip freeze	pip freeze
Sync env	uv sync	pip install -r requirements.txt
Update package	uv update package	pip install --upgrade package

Environment Types

Development Environment

# Complete development setup
uv venv
uv add --dev pytest black flake8 mypy
uv add pandas numpy matplotlib
uv sync

Production Environment

# Production-ready with pinned versions
uv venv --python 3.11
uv add "package==1.2.3"  # Pin exact versions
uv pip compile requirements.in -o requirements.txt

CI/CD Environment

# Minimal environment for CI
uv venv --python 3.11
uv add --no-dev package-name
uv sync --frozen

Project Structure

Recommended Layout

project/
├── .venv/                 # Virtual environment (gitignored)
├── src/                   # Source code
├── tests/                 # Test files
├── pyproject.toml         # Project configuration
├── requirements.txt       # Pinned dependencies
├── requirements-dev.txt   # Development dependencies
└── .python-version       # Python version specification

Configuration Files

pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
description = "My project description"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
    "pandas>=1.5.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "flake8>=6.0.0",
]

[tool.uv]
# uv-specific settings

requirements.txt

# Pinned dependencies
requests==2.28.2
pandas==1.5.3
numpy==1.24.3

Common Workflows

New Project Setup

# 1. Create project directory
mkdir my-project && cd my-project

# 2. Initialize with uv
uv init

# 3. Create virtual environment
uv venv

# 4. Activate environment
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# 5. Add initial dependencies
uv add requests pandas
uv add --dev pytest black

# 6. Create basic project structure
mkdir src tests
touch src/__init__.py tests/__init__.py

# 7. Create .gitignore
echo ".venv/" >> .gitignore
echo "__pycache__/" >> .gitignore
echo "*.pyc" >> .gitignore

Existing Project Setup

# 1. Clone repository
git clone https://github.com/user/project.git
cd project

# 2. Create environment with specific Python version
uv venv --python 3.11

# 3. Install dependencies
uv sync

# 4. Activate environment
source .venv/bin/activate

Real-world example: The YouTube-SC project includes complete setup scripts (setup-environment.bat and setup-environment.sh) and a comprehensive requirements.txt file. See examples/youtube-sc/ for details.

Dependency Updates

# Check for updates
uv update --outdated

# Update all packages
uv update

# Update specific package
uv update package-name

# Update with constraints
uv update --pre  # Include pre-release versions

Troubleshooting

Common Issues

1. Environment Activation Fails

Symptoms: source .venv/bin/activate doesn't work Solutions:

# Check if .venv exists
ls -la .venv/

# Try alternative activation
. .venv/bin/activate  # Note the space after the dot

# On Windows, use:
.venv\Scripts\activate

2. Package Installation Failures

Symptoms: uv add package fails with errors Solutions:

# Clear uv cache
uv cache clean

# Try with verbose output
uv add package -v

# Check Python version compatibility
python --version

# Try different package version
uv add "package>=1.0.0,<2.0.0"

3. Dependency Conflicts

Symptoms: uv sync fails with resolution errors Solutions:

# Use resolution strategy
uv sync --resolution=highest
uv sync --resolution=lowest-direct

# Check existing dependencies
uv pip list

# Remove conflicting package
uv remove conflicting-package

4. Slow Package Installation

Symptoms: uv is slow (unusual) Solutions:

# Use uv's native resolver (already fast)
# Check network connection

# Use mirror or local cache
uv config set global.index-url "https://pypi.tuna.tsinghua.edu.cn/simple"

# Pre-download packages
uv pip download package -d ./packages

Advanced Features

Lock Files

# Generate lock file
uv pip compile requirements.in -o requirements.txt

# Install from lock file
uv sync --frozen

Multiple Python Versions

# Create environment with specific Python version
uv venv --python 3.11
uv venv --python 3.10
uv venv --python 3.9

# List available Python versions
uv python list

Environment Isolation

# Create isolated environment
uv venv --isolated

# Copy existing environment
uv venv --copies

Cross-Platform Compatibility

# Generate platform-specific requirements
uv pip compile requirements.in --platform linux --platform macos --platform windows

# Install platform-specific packages
uv add "package; sys_platform == 'linux'"

Integration with Other Tools

IDE Integration

VS Code: Add to settings.json:

{
    "python.defaultInterpreterPath": ".venv/bin/python",
    "terminal.integrated.env.windows": {
        "VIRTUAL_ENV": "${workspaceFolder}/.venv"
    }
}

PyCharm:

• File → Settings → Project → Python Interpreter
• Add → Existing environment → Select .venv/bin/python

Docker Integration

FROM python:3.11-slim

# Install uv
RUN pip install uv

# Copy project files
COPY . /app
WORKDIR /app

# Create virtual environment and install dependencies
RUN uv venv && uv sync --frozen

# Use the virtual environment
ENV PATH="/app/.venv/bin:$PATH"

CMD ["python", "main.py"]

CI/CD Integration

# GitHub Actions example
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv sync --frozen
      - run: uv run pytest

Best Practices

1. Version Pinning

• Pin exact versions in production (==)
• Use ranges in development (>=)
• Maintain separate requirements files for dev/prod

2. Environment Management

• Keep .venv in project directory (not global)
• Include .venv in .gitignore
• Document Python version requirement

3. Dependency Hygiene

• Regularly update dependencies
• Remove unused packages
• Audit for security vulnerabilities

4. Reproducibility

• Use lock files for exact reproducibility
• Document environment setup in README
• Test across Python versions

Resources

• uv Documentation: See references/uv-docs.md for complete uv reference
• Common Recipes: See references/recipes.md for common environment setups
• Troubleshooting Guide: See references/troubleshooting.md for solving common issues
• Migration Guide: See references/migration.md for migrating from pip/venv
• Project Examples: See examples/youtube-sc/ for real-world configuration files from the YouTube-SC project

When to Use This Skill

Use this skill when:

• Setting up new Python projects
• Managing dependencies for existing projects
• Troubleshooting environment issues
• Creating reproducible environments
• Migrating from pip/venv to uv
• Setting up CI/CD pipelines
• Managing multiple Python versions
• Ensuring cross-platform compatibility