Uv Package Manager

by wshobson46891e7e60daNo licenseListed Oct 8, 2026Updated Oct 8, 2026

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.

Instructions only

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

# Using Homebrew (macOS or Linux)brew install uv
# Using Cargo (if you have Rust)cargo install --locked uv

On Windows, use WinGet:

Use the official installation guide for other supported installation methods.

Verify Installation

Quick Start

Create a New Project

bash

# Create new project with virtual environmentuv init my-projectcd my-project
# Or create in current directoryuv init .
# Initialize creates:# - .python-version (Python version)# - pyproject.toml (project config)# - README.md# - .gitignore

# Create new project with virtual environmentuv init my-projectcd my-project
# Or create in current directoryuv 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 dependenciesuv add --dev pytest black ruff
# Install from requirements.txtuv pip install -r requirements.txt
# Install from pyproject.tomluv sync

# Install packages (creates venv if needed)uv add requests pandas
# Install dev dependenciesuv add --dev pytest black ruff
# Install from requirements.txtuv pip install -r requirements.txt
# Install from pyproject.tomluv sync

Virtual Environment Management

Pattern 1: Creating Virtual Environments

bash

# Create virtual environment with uvuv venv
# Create with specific Python versionuv venv --python 3.12
# Create with custom nameuv venv my-env
# Create with system site packagesuv venv --system-site-packages
# Specify locationuv venv /path/to/venv

# Create virtual environment with uvuv venv
# Create with specific Python versionuv venv --python 3.12
# Create with custom nameuv venv my-env
# Create with system site packagesuv venv --system-site-packages
# Specify locationuv venv /path/to/venv

Pattern 2: Activating Virtual Environments

bash

# Linux/macOSsource .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.pyuv run pytest

# Linux/macOSsource .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.pyuv run pytest

Pattern 3: Using uv run

bash

# Run Python script (auto-activates venv)uv run python app.py
# Run installed CLI tooluv run black .uv run pytest
# Run with specific Python versionuv run --python 3.11 python script.py
# Pass argumentsuv run python script.py --arg value

# Run Python script (auto-activates venv)uv run python app.py
# Run installed CLI tooluv run black .uv run pytest
# Run with specific Python versionuv run --python 3.11 python script.py
# Pass argumentsuv 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 constraintuv add "django>=4.0,<5.0"
# Add multiple packagesuv add numpy pandas matplotlib
# Add dev dependencyuv add --dev pytest pytest-cov
# Add optional dependency groupuv add --optional docs sphinx
# Add from gituv add git+https://github.com/user/repo.git
# Add from git with specific refuv add git+https://github.com/user/[email protected]
# Add from local pathuv add ./local-package
# Add editable local packageuv add -e ./local-package

# Add package (adds to pyproject.toml)uv add requests
# Add with version constraintuv add "django>=4.0,<5.0"
# Add multiple packagesuv add numpy pandas matplotlib
# Add dev dependencyuv add --dev pytest pytest-cov
# Add optional dependency groupuv add --optional docs sphinx
# Add from gituv add git+https://github.com/user/repo.git
# Add from git with specific refuv add git+https://github.com/user/[email protected]
# Add from local pathuv add ./local-package
# Add editable local packageuv add -e ./local-package

Pattern 5: Removing Dependencies

bash

# Remove packageuv remove requests
# Remove dev dependencyuv remove --dev pytest
# Remove multiple packagesuv remove numpy pandas matplotlib

# Remove packageuv remove requests
# Remove dev dependencyuv remove --dev pytest
# Remove multiple packagesuv remove numpy pandas matplotlib

Pattern 6: Upgrading Dependencies

bash

# Upgrade specific packageuv add --upgrade requests
# Upgrade all packagesuv sync --upgrade
# Upgrade package to latestuv add --upgrade requests
# Show what would be upgradeduv tree --outdated

# Upgrade specific packageuv add --upgrade requests
# Upgrade all packagesuv sync --upgrade
# Upgrade package to latestuv add --upgrade requests
# Show what would be upgradeduv tree --outdated

Pattern 7: Locking Dependencies

bash

# Generate uv.lock fileuv lock
# Update lock fileuv lock --upgrade
# Lock without installinguv lock --no-install
# Lock specific packageuv lock --upgrade-package requests

# Generate uv.lock fileuv lock
# Update lock fileuv lock --upgrade
# Lock without installinguv lock --no-install
# Lock specific packageuv lock --upgrade-package requests

Python Version Management

Pattern 8: Installing Python Versions

bash

# Install Python versionuv python install 3.12
# Install multiple versionsuv python install 3.11 3.12 3.13
# Install latest versionuv python install
# List installed versionsuv python list
# Find available versionsuv python list --all-versions

# Install Python versionuv python install 3.12
# Install multiple versionsuv python install 3.11 3.12 3.13
# Install latest versionuv python install
# List installed versionsuv python list
# Find available versionsuv python list --all-versions

Pattern 9: Setting Python Version

bash

# Set Python version for projectuv python pin 3.12
# This creates/updates .python-version file
# Use specific Python version for commanduv --python 3.11 run python script.py
# Create venv with specific versionuv venv --python 3.12

# Set Python version for projectuv python pin 3.12
# This creates/updates .python-version file
# Use specific Python version for commanduv --python 3.11 run python script.py
# Create venv with specific versionuv 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 sourcesmy-package = { git = "https://github.com/user/repo.git" }

[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 sourcesmy-package = { git = "https://github.com/user/repo.git" }

Pattern 11: Using uv with Existing Projects

bash

# Migrate from requirements.txtuv add -r requirements.txt
# Migrate from poetry# Already have pyproject.toml, just use:uv sync
# Export to requirements.txtuv pip freeze > requirements.txt
# Export with hashesuv pip freeze --require-hashes > requirements.txt

# Migrate from requirements.txtuv add -r requirements.txt
# Migrate from poetry# Already have pyproject.toml, just use:uv sync
# Export to requirements.txtuv pip freeze > requirements.txt
# Export with hashesuv 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 [blocked]

Source and attribution

Source:wshobson/agentsinplugins/python-development/skills/uv-package-managerat commit46891e7

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from wshobson/agents

Web Component Design

wshobson

Master React, Vue, and Svelte component patterns including CSS-in-JS, composition strategies, and reusable component architecture. Use when building UI component libraries, designing component APIs, or implementing frontend design systems.

Awaiting classificationOct 8, 2026

Python Type Safety

wshobson

Guides Python type annotations, generics, protocols, and strict mypy/pyright checking.

Software DevelopmentOct 8, 2026

Visual Design Foundations

wshobson

Guides typography, color, spacing and iconography decisions for cohesive, accessible visual design systems.

Design & CreativeOct 8, 2026

Responsive Design

wshobson

Guides implementation of responsive web layouts using container queries, fluid typography, CSS Grid and breakpoints.

Software DevelopmentOct 8, 2026

Python Resource Management

wshobson

Python resource management with context managers, cleanup patterns, and streaming. Use when managing connections, file handles, implementing cleanup logic, or building streaming responses with accumulated state.

Awaiting classificationOct 8, 2026

React Native Design

wshobson

Master React Native styling, navigation, and Reanimated animations for cross-platform mobile development. Use when building React Native apps, implementing navigation patterns, or creating performant animations.

Awaiting classificationOct 8, 2026