manage-python-env

name

manage-python-env

description

Python virtual environment management using uv for fast and reliable environment setup. Create, maintain, and manage Python virtual environments with dependency management. Use uv for environment creation, package installation, dependency resolution, and project configuration. Use when setting up new Python projects, managing dependencies, troubleshooting environment issues, or ensuring reproducible development environments.

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