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

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

# 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

Search AI Tools

Install this agent skill to your Project

SKILL.md

Python Environment Management Skill

Quick Start

Core Workflow

1. Environment Setup

2. Dependency Management

3. Project Configuration

uv vs Traditional Tools

Advantages of uv

Command Comparison

Environment Types

Development Environment

Production Environment

CI/CD Environment

Project Structure

Recommended Layout

Configuration Files

pyproject.toml

requirements.txt

Common Workflows

New Project Setup

Existing Project Setup

Dependency Updates

Troubleshooting

Common Issues

1. Environment Activation Fails

2. Package Installation Failures

3. Dependency Conflicts

4. Slow Package Installation

Advanced Features

Lock Files

Multiple Python Versions

Environment Isolation

Cross-Platform Compatibility

Integration with Other Tools

IDE Integration

Docker Integration

CI/CD Integration

Best Practices

1. Version Pinning

2. Environment Management

3. Dependency Hygiene

4. Reproducibility

Resources

When to Use This Skill