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

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

Core Workflow

1. Environment Setup

bash

# 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

bash

# 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

bash

# 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

bash

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

Production Environment

bash

# 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

bash

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

Project Structure

Recommended Layout

code

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

[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

code

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

Common Workflows

New Project Setup

bash

# 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

bash

# 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

bash

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

bash

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

bash

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

bash

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

bash

# 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

bash

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

# Install from lock file
uv sync --frozen

Multiple Python Versions

bash

# 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

bash

# Create isolated environment
uv venv --isolated

# Copy existing environment
uv venv --copies

Cross-Platform Compatibility

bash

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

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

dockerfile

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

yaml

# 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