Skip to main content
Agent skill

Uv Package Manager

Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimizing Python development workflows with uv.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Uv Package Manager when an AI agent needs a reusable SKILL.md workflow for this job: Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimizing Python development workflows with uv.

When not to use it

Skip Uv Package Manager when the task is outside the productivity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/uv-package-manager
# Save SKILL.md to ~/.claude/skills/uv-package-manager/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/uv-package-manager/SKILL.md. For a shared project, commit the folder at .claude/skills/uv-package-manager/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Uv Package Manager skill for this task: Setting up new Python projects quickly. Confirm any required inputs or files before making changes.

What supports this recommendation?

84/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
92/100
Practical detail
92/100
Source evidence
63/100
Source signals
80/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# UV Package Manager

Comprehensive guide to using uv, an extremely fast Python package installer and resolver written in Rust, for modern Python project management and dependency workflows.

## When to Use This Skill

- Setting up new Python projects quickly - Managing Python dependencies faster than pip - Creating and managing virtual environments - Installing Python interpreters - Resolving dependency conflicts efficiently - Migrating from pip/pip-tools/poetry - Speeding up CI/CD pipelines - Managing monorepo Python projects - Working with lockfiles for reproducible builds - Optimizing Docker builds with Python dependencies

## Core Concepts

### 1. What is uv?

- **Ultra-fast package installer**: 10-100x faster than pip - **Written in Rust**: Leverages Rust's performance - **Drop-in pip replacement**: Compatible with pip workflows - **Virtual environment manager**: Create and manage venvs - **Python installer**: Download and manage Python versions - **Resolver**: Advanced dependency resolution - **Lockfile support**: Reproducible installations

### 2. Key Features

- Blazing fast installation speeds - Disk space efficient with global cache - Compatible with pip, pip-tools, poetry - Comprehensive dependency resolution - Cross-platform support (Linux, macOS, Windows) - No Python required for installation - Built-in virtual environment support

### 3. UV vs Traditional Tools

- **vs pip**: 10-100x faster, better resolver - **vs pip-tools**: Faster, simpler, better UX - **vs poetry**: Faster, less opinionated, lighter - **vs conda**: Faster, Python-focused

## Installation

### Quick Install

```bash # Using Homebrew (macOS or Linux) brew install uv

# Using Cargo (if you have Rust) cargo install --locked uv ```

On Windows, use WinGet:

```powershell winget install --id=astral-sh.uv -e ```

Use the [official installation guide](https://docs.astral.sh/uv/getting-started/installation/) for other supported installation methods.

### Verify Installation

```bash uv --version # uv 0.x.x ```

## Quick Start

### Create a New Project

```bash # Create new project with virtual environment uv init my-project cd my-project

# Or create in current directory uv init .

# Initialize creates: # - .python-version (Python version) # - pyproject.toml (project config) # - README.md # - .gitignore ```

### Install Dependencies

```bash # Install packages (creates venv if needed) uv add requests pandas

# Install dev dependencies uv add --dev pytest black ruff

# Install from requirements.txt uv pip install -r requirements.txt

# Install from pyproject.toml uv sync ```

## Virtual Environment Management

### Pattern 1: Creating Virtual Environments

```bash # Create virtual environment with uv uv venv

# Create with specific Python version uv venv --python 3.12

# Create with custom name uv venv my-env

# Create with system site packages uv venv --system-site-packages

# Specify location uv venv /path/to/venv ```

### Pattern 2: Activating Virtual Environments

```bash # Linux/macOS source .venv/bin/activate

# Windows (Command Prompt) .venv\Scripts\activate.bat

# Windows (PowerShell) .venv\Scripts\Activate.ps1

# Or use uv run (no activation needed) uv run python script.py uv run pytest ```

### Pattern 3: Using uv run

```bash # Run Python script (auto-activates venv) uv run python app.py

# Run installed CLI tool uv run black . uv run pytest

# Run with specific Python version uv run --python 3.11 python script.py

# Pass arguments uv run python script.py --arg value ```

## Package Management

### Pattern 4: Adding Dependencies

```bash # Add package (adds to pyproject.toml) uv add requests

# Add with version constraint uv add "django>=4.0,<5.0"

# Add multiple packages uv add numpy pandas matplotlib

# Add dev dependency uv add --dev pytest pytest-cov

# Add optional dependency group uv add --optional docs sphinx

# Add from git uv add git+https://github.com/user/repo.git

# Add from git with specific ref uv add git+https://github.com/user/[email protected]

# Add from local path uv add ./local-package

# Add editable local package uv add -e ./local-package ```

### Pattern 5: Removing Dependencies

```bash # Remove package uv remove requests

# Remove dev dependency uv remove --dev pytest

# Remove multiple packages uv remove numpy pandas matplotlib ```

### Pattern 6: Upgrading Dependencies

```bash # Upgrade specific package uv add --upgrade requests

# Upgrade all packages uv sync --upgrade

# Upgrade package to latest uv add --upgrade requests

# Show what would be upgraded uv tree --outdated ```

### Pattern 7: Locking Dependencies

```bash # Generate uv.lock file uv lock

# Update lock file uv lock --upgrade

# Lock without installing uv lock --no-install

# Lock specific package uv lock --upgrade-package requests ```

## Python Version Management

### Pattern 8: Installing Python Versions

```bash # Install Python version uv python install 3.12

# Install multiple versions uv python install 3.11 3.12 3.13

# Install latest version uv python install

# List installed versions uv python list

# Find available versions uv python list --all-versions ```

### Pattern 9: Setting Python Version

```bash # Set Python version for project uv python pin 3.12

# This creates/updates .python-version file

# Use specific Python version for command uv --python 3.11 run python script.py

# Create venv with specific version uv venv --python 3.12 ```

## Project Configuration

### Pattern 10: pyproject.toml with uv

```toml [project] name = "my-project" version = "0.1.0" description = "My awesome project" readme = "README.md" requires-python = ">=3.8" dependencies = [ "requests>=2.31.0", "pydantic>=2.0.0", "click>=8.1.0", ]

[project.optional-dependencies] dev = [ "pytest>=7.4.0", "pytest-cov>=4.1.0", "black>=23.0.0", "ruff>=0.1.0", "mypy>=1.5.0", ] docs = [ "sphinx>=7.0.0", "sphinx-rtd-theme>=1.3.0", ]

[build-system] requires = ["hatchling"] build-backend = "hatchling.build"

[tool.uv] dev-dependencies = [ # Additional dev dependencies managed by uv ]

[tool.uv.sources] # Custom package sources my-package = { git = "https://github.com/user/repo.git" } ```

### Pattern 11: Using uv with Existing Projects

```bash # Migrate from requirements.txt uv add -r requirements.txt

# Migrate from poetry # Already have pyproject.toml, just use: uv sync

# Export to requirements.txt uv pip freeze > requirements.txt

# Export with hashes uv pip freeze --require-hashes > requirements.txt ```

For advanced workflows including Docker integration, lockfile management, performance optimization, tool comparison, common workflows, tool integration, troubleshooting, best practices, migration guides, and command reference, see [references/advanced-patterns.md](references/advanced-patterns.md)

Intended uses

  • Setting up new Python projects quickly
  • Managing Python dependencies faster than pip
  • Creating and managing virtual environments
  • Installing Python interpreters
  • Resolving dependency conflicts efficiently
  • Migrating from pip/pip-tools/poetry
  • Speeding up CI/CD pipelines
  • Managing monorepo Python projects
  • Working with lockfiles for reproducible builds
  • Optimizing Docker builds with Python dependencies

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.