python-package-management

name

python-package-management

description

Manages Python projects using UV package manager exclusively. Use when users need to create Python projects, manage dependencies, handle virtual environments, or work with Python packages. This skill enforces UV workflows for all Python package operations including installing packages, creating projects, managing dependencies, running scripts, and building distributions. NOT when working with existing pip/poetry projects that user explicitly wants to keep unchanged.

Python Package Management with UV

This skill provides expert guidance for managing Python projects using UV, the ultra-fast Rust-based package manager. UV replaces pip, pip-tools, virtualenv, poetry, pyenv, and more with a single, blazing-fast tool.

Core Principles

1. UV-First Approach: Always use UV for Python package management
2. Automatic Environment Management: UV handles virtual environments automatically
3. Lock Files for Reproducibility: UV maintains uv.lock for deterministic builds
4. Project-Based Workflow: All Python work happens within UV-managed projects

Project Initialization

Creating New Projects

UV supports different project types based on use case:

Standard Application (default)

uv init myapp
cd myapp

Creates: Flat structure with main.py, no build system. For web apps, scripts, non-distributed applications.

Packaged Application

uv init --package myapp
cd myapp

Creates: src/ layout with build system and console script entry points. For CLI tools distributed via PyPI.

Library

uv init --lib mylib
cd mylib

Creates: src/ layout with build system, py.typed marker. For reusable libraries published to PyPI.

Project Type Selection Guide:

• Web server/internal script → Standard app (uv init)
• CLI tool for distribution → Packaged app (uv init --package)
• Reusable library for PyPI → Library (uv init --lib)

Project Structure

After initialization, projects contain:

myproject/
├── .venv/              # Created on first uv run/sync
├── .python-version     # Python version pin
├── .gitignore         # Pre-configured for Python
├── pyproject.toml     # Project metadata & dependencies
├── uv.lock           # Generated on first uv run/sync
├── README.md
└── main.py or src/   # Code location based on type

Dependency Management

Adding Dependencies

Production dependencies:

uv add requests
uv add "fastapi>=0.100.0"
uv add git+https://github.com/user/repo.git

Development dependencies:

uv add --dev pytest ruff mypy
uv add --dev "black>=24.0"

Optional dependency groups:

uv add --group docs sphinx sphinx-rtd-theme
uv add --group lint ruff

From requirements.txt:

uv add -r requirements.txt

Removing Dependencies

uv remove requests
uv remove --dev pytest  # Remove from dev group
uv remove --group docs sphinx  # Remove from optional group

Note: uv remove automatically removes transitive dependencies that are no longer needed.

Managing Dependencies

Lock dependencies (update uv.lock from pyproject.toml):

uv lock

Sync environment (install from uv.lock):

uv sync
uv sync --no-dev  # Exclude dev dependencies
uv sync --group docs  # Include optional group
uv sync --all-groups  # Include all groups

Upgrade specific package:

uv lock --upgrade-package requests

Upgrade all packages:

uv lock --upgrade

Running Code

Execute Scripts/Commands

UV automatically creates/syncs environment before running:

uv run python script.py
uv run python -m module_name
uv run pytest
uv run myapp  # For packaged apps with console scripts

With temporary dependencies:

uv run --with requests python script.py
uv run --with "numpy>=1.20" python analysis.py

Skip auto-sync (when environment is known up-to-date):

uv run --no-sync python script.py

Interactive Python

uv run python  # Launch Python REPL
uv run ipython  # If ipython is a dependency

Python Version Management

Install Python Versions

uv python install 3.12
uv python install 3.11 3.12 3.13  # Install multiple
uv python list  # List available versions

Pin Project Python Version

uv python pin 3.12  # Creates/updates .python-version
uv python pin 3.12.5  # Pin specific patch version

Use Specific Python Version

uv venv --python 3.11
uv run --python 3.12 python script.py

Virtual Environment Operations

While UV manages environments automatically, manual operations are available:

Create virtual environment:

uv venv  # Creates .venv/
uv venv --python 3.12  # With specific Python version

Manual activation (rarely needed with uv run):

source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate  # Windows

Why UV's auto-management is preferred:

• uv run automatically uses project environment
• No manual activation needed
• Guarantees environment is synced with lockfile
• Prevents "works on my machine" issues

Tool Management

UV provides uvx (alias for uv tool run) for running CLI tools without installing them in the project:

Run tool once:

uvx ruff check .
uvx black --check .
uvx pytest

Install tool globally:

uv tool install ruff
uv tool install black

List installed tools:

uv tool list

Update tool:

uv tool upgrade ruff

Building and Publishing

Build Distributions

uv build  # Creates wheel and sdist in dist/
uv build --wheel  # Only wheel
uv build --sdist  # Only source distribution

Publishing

For packaged libraries:

uv publish  # Publishes to PyPI
uv publish --token <token>  # With API token

Migration from Other Tools

From pip + virtualenv

# Old workflow
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# UV workflow
uv init .  # In existing directory
uv add -r requirements.txt
uv run python script.py

From Poetry

# Poetry project structure works with UV
uv sync  # Reads existing pyproject.toml
uv run pytest  # Replaces poetry run pytest

From requirements.txt

# Generate pyproject.toml from requirements
uv init .
uv add -r requirements.txt
# Creates pyproject.toml with those dependencies

Common Workflows

New Project Setup

# 1. Create project
uv init --package myproject
cd myproject

# 2. Add dependencies
uv add fastapi uvicorn
uv add --dev pytest ruff

# 3. Run code
uv run python -m myproject

# 4. Run tests
uv run pytest

Daily Development

# Add new dependency
uv add new-package

# Run application
uv run python main.py

# Run tests
uv run pytest

# Format code (using tools)
uvx ruff format .

# Check types
uvx mypy src/

Collaboration Workflow

# Clone repository
git clone <repo-url>
cd project

# Install dependencies (UV handles everything)
uv sync

# Run application
uv run python main.py

# Add feature
uv add new-dependency
git add pyproject.toml uv.lock
git commit -m "Add new dependency"

CI/CD Setup

# In CI pipeline
uv sync --frozen  # Fail if lockfile is outdated
uv run pytest
uv build

Key Flags and Options

Lock Behavior

• --locked: Fail if lockfile needs update (CI/CD)
• --frozen: Use lockfile without checking if current (fastest)
• --upgrade: Upgrade all packages to latest compatible
• --upgrade-package <pkg>: Upgrade specific package

Sync Behavior

• --no-dev: Exclude development dependencies
• --all-groups: Include all optional groups
• --group <name>: Include specific group
• --no-group <name>: Exclude specific group
• --exact: Remove packages not in lockfile

Run Behavior

• --with <pkg>: Add temporary dependency
• --no-sync: Skip environment sync check
• --python <version>: Use specific Python version
• --no-project: Run in isolated environment

Troubleshooting

Environment Issues

Environment out of sync:

rm -rf .venv
uv sync

Lockfile conflicts after merge:

uv lock
uv sync

Python version mismatch:

uv python install 3.12
uv python pin 3.12
uv sync

Dependency Conflicts

Check for conflicts:

uv tree  # Show dependency tree

Force resolution update:

uv lock --upgrade

Performance Tips

Use global cache (automatic):

• UV caches packages globally at ~/.cache/uv/
• Deduplicates across projects
• Dramatically speeds up repeated installs

Leverage frozen lockfile in production:

uv sync --frozen  # Skip staleness check

Best Practices

1. Always commit uv.lock: Ensures reproducible builds across team
2. Use uv run over manual activation: Guarantees correct environment
3. Pin Python version: Add .python-version to repository
4. Use dependency groups: Separate dev/test/docs dependencies
5. Let UV manage everything: Don't mix pip/poetry commands
6. Leverage uvx for tools: Keep project dependencies clean
7. Use --frozen in CI: Fail fast on lockfile issues

Quick Reference

# Project lifecycle
uv init --package myapp          # Create project
uv add requests                  # Add dependency
uv run python main.py            # Run code
uv sync                          # Sync environment
uv lock                          # Update lockfile

# Development
uv add --dev pytest              # Add dev dependency
uv run pytest                    # Run tests
uvx ruff format .                # Format code

# Python management  
uv python install 3.12           # Install Python
uv python pin 3.12               # Pin version

# Tools
uvx ruff check .                 # Run tool once
uv tool install ruff             # Install globally

# Build & publish
uv build                         # Build distributions
uv publish                       # Publish to PyPI

When NOT to Use This Skill

• User explicitly wants to keep existing pip/poetry workflow
• Working in non-Python projects
• User is debugging UV itself
• Legacy Python 2 projects (UV requires Python 3.8+)