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

bash
1# Initialize project with uv
2uv init project-name
3cd project-name
4
5# Create virtual environment
6uv venv
7
8# Activate environment
9# On Windows:
10.venv\Scripts\activate
11# On Unix/Mac:
12source .venv/bin/activate

2. Dependency Management

bash
1# Install packages
2uv add package-name
3uv add "package-name>=1.0.0"
4uv add "package-name[extra]"
5
6# Install from requirements.txt
7uv pip install -r requirements.txt
8
9# Install with development dependencies
10uv add --dev pytest black

3. Project Configuration

bash
1# Generate requirements.txt
2uv pip freeze > requirements.txt
3
4# Sync environment
5uv sync
6
7# Update packages
8uv update
9uv 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

Environment Types

Development Environment

bash
1# Complete development setup
2uv venv
3uv add --dev pytest black flake8 mypy
4uv add pandas numpy matplotlib
5uv sync

Production Environment

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

CI/CD Environment

bash
1# Minimal environment for CI
2uv venv --python 3.11
3uv add --no-dev package-name
4uv 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

toml
1[project]
2name = "my-project"
3version = "0.1.0"
4description = "My project description"
5requires-python = ">=3.8"
6dependencies = [
7    "requests>=2.28.0",
8    "pandas>=1.5.0",
9]
10
11[project.optional-dependencies]
12dev = [
13    "pytest>=7.0.0",
14    "black>=23.0.0",
15    "flake8>=6.0.0",
16]
17
18[tool.uv]
19# uv-specific settings

requirements.txt

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

Common Workflows

New Project Setup

bash
1# 1. Create project directory
2mkdir my-project && cd my-project
3
4# 2. Initialize with uv
5uv init
6
7# 3. Create virtual environment
8uv venv
9
10# 4. Activate environment
11source .venv/bin/activate  # or .venv\Scripts\activate on Windows
12
13# 5. Add initial dependencies
14uv add requests pandas
15uv add --dev pytest black
16
17# 6. Create basic project structure
18mkdir src tests
19touch src/__init__.py tests/__init__.py
20
21# 7. Create .gitignore
22echo ".venv/" >> .gitignore
23echo "__pycache__/" >> .gitignore
24echo "*.pyc" >> .gitignore

Existing Project Setup

bash
1# 1. Clone repository
2git clone https://github.com/user/project.git
3cd project
4
5# 2. Create environment with specific Python version
6uv venv --python 3.11
7
8# 3. Install dependencies
9uv sync
10
11# 4. Activate environment
12source .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

bash
1# Check for updates
2uv update --outdated
3
4# Update all packages
5uv update
6
7# Update specific package
8uv update package-name
9
10# Update with constraints
11uv update --pre  # Include pre-release versions

Troubleshooting

Common Issues

1. Environment Activation Fails

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

bash
1# Check if .venv exists
2ls -la .venv/
3
4# Try alternative activation
5. .venv/bin/activate  # Note the space after the dot
6
7# On Windows, use:
8.venv\Scripts\activate

2. Package Installation Failures

Symptoms: uv add package fails with errors Solutions:

bash
1# Clear uv cache
2uv cache clean
3
4# Try with verbose output
5uv add package -v
6
7# Check Python version compatibility
8python --version
9
10# Try different package version
11uv add "package>=1.0.0,<2.0.0"

3. Dependency Conflicts

Symptoms: uv sync fails with resolution errors Solutions:

bash
1# Use resolution strategy
2uv sync --resolution=highest
3uv sync --resolution=lowest-direct
4
5# Check existing dependencies
6uv pip list
7
8# Remove conflicting package
9uv remove conflicting-package

4. Slow Package Installation

Symptoms: uv is slow (unusual) Solutions:

bash
1# Use uv's native resolver (already fast)
2# Check network connection
3
4# Use mirror or local cache
5uv config set global.index-url "https://pypi.tuna.tsinghua.edu.cn/simple"
6
7# Pre-download packages
8uv pip download package -d ./packages

Advanced Features

Lock Files

bash
1# Generate lock file
2uv pip compile requirements.in -o requirements.txt
3
4# Install from lock file
5uv sync --frozen

Multiple Python Versions

bash
1# Create environment with specific Python version
2uv venv --python 3.11
3uv venv --python 3.10
4uv venv --python 3.9
5
6# List available Python versions
7uv python list

Environment Isolation

bash
1# Create isolated environment
2uv venv --isolated
3
4# Copy existing environment
5uv venv --copies

Cross-Platform Compatibility

bash
1# Generate platform-specific requirements
2uv pip compile requirements.in --platform linux --platform macos --platform windows
3
4# Install platform-specific packages
5uv add "package; sys_platform == 'linux'"

Integration with Other Tools

IDE Integration

VS Code: Add to settings.json:

json
1{
2    "python.defaultInterpreterPath": ".venv/bin/python",
3    "terminal.integrated.env.windows": {
4        "VIRTUAL_ENV": "${workspaceFolder}/.venv"
5    }
6}

PyCharm:

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

Docker Integration

dockerfile
1FROM python:3.11-slim
2
3# Install uv
4RUN pip install uv
5
6# Copy project files
7COPY . /app
8WORKDIR /app
9
10# Create virtual environment and install dependencies
11RUN uv venv && uv sync --frozen
12
13# Use the virtual environment
14ENV PATH="/app/.venv/bin:$PATH"
15
16CMD ["python", "main.py"]

CI/CD Integration

yaml
1# GitHub Actions example
2jobs:
3  test:
4    runs-on: ubuntu-latest
5    steps:
6      - uses: actions/checkout@v4
7      - uses: astral-sh/setup-uv@v3
8      - run: uv sync --frozen
9      - 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