Uv 0 11 8

uv 0.11.8

Changes Since 0.11.6

0.11.8 (2026-04-27)

• --python-downloads-json-url flag added to uv python pin
• Self-update fetches from Astral mirror
• pip uninstall -y supported
• exclude-newer can be omitted from lockfile when exclude-newer-span is present
• Sentinel timestamps for relative exclude-newer and exclude-newer-package in lockfiles
• New env vars: UV_PYTHON_NO_REGISTRY, env var for UV_NO_PROJECT, UV_PYTHON_SEARCH_PATH
• Bug fixes: git env isolation, pre-signed URL redaction, transitive URL deps in PEP 517 builds, uv lock with dependency-groups-only pyproject.toml, transparent Python upgrades disabled when patch pinned via .python-version, Windows registry variant tagging, external symlinks banned in .tar.zst wheels
• uv-build: removed deprecated license classifiers, added Python 3.14 classifier

0.11.7 (2026-04-15)

• CPython build upgraded (20260414) with OpenSSL security upgrade
• Configuration errors elevated to required-version mismatches
• Improved TLS certificate validation messages and --exclude-newer hints
• uv audit: fixed --script handling and extras traversal
• Bug fixes: workspace metadata quoting, tool workspace member editable installs, JSON report for uv sync --check, TLS cert filtering, ~= specifier equality, stale Python upgrade preview check, Windows path normalization

Overview

uv is an extremely fast Python package and project manager, written in Rust. It replaces pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more — with 10-100x faster performance across all operations.

uv provides three primary interfaces:

• Projects — Full project management with lockfiles, dependency resolution, and automatic environment management (uv init, uv add, uv sync, uv run, uv lock)
• Tools — Install and run Python CLI tools without polluting your system (uv tool install, uvx)
• Python versions — Discover, install, and manage Python interpreters (uv python install)

It also includes a drop-in replacement for pip (uv pip), venv creation (uv venv), package building (uv build), and publishing to PyPI (uv publish).

When to Use

• Creating new Python projects with uv init
• Managing project dependencies with lockfiles (uv add, uv sync, uv lock)
• Running commands in isolated project environments (uv run)
• Installing and running one-off Python CLI tools (uvx, uv tool install)
• Managing Python interpreter versions across projects (uv python install)
• Replacing pip workflows with faster equivalents (uv pip install, uv pip compile)
• Building and publishing Python packages (uv build, uv publish)
• Working with monorepos via workspaces
• Setting up CI/CD with reproducible lockfiles

Core Concepts

Three Interfaces

uv organizes its functionality into three interfaces:

1. Project interface — The primary, high-level workflow for managing Python projects with automatic environment and lockfile management
2. Tool interface — For installing and running standalone Python CLI tools
3. pip interface — A drop-in replacement for pip, pip-tools, and virtualenv commands

Universal Lockfiles

uv generates a uv.lock file that is universal (cross-platform). It captures the packages that would be installed across all possible Python markers — operating system, architecture, and Python version. Unlike requirements.txt, this lockfile is checked into version control for reproducible installations.

Automatic Lock and Sync

Locking and syncing are automatic in uv. When you run uv run, the project is locked and synced before invoking the command. This ensures the environment is always up-to-date without manual steps.

Managed Python Versions

uv can install Python versions itself (managed Python) or discover existing system installations. By default, it automatically downloads Python versions as needed. Use uv python install to explicitly install versions, and .python-version files to pin versions per-project.

Installation / Setup

Standalone Installer (Recommended)

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Request a specific version:

curl -LsSf https://astral.sh/uv/0.11.8/install.sh | sh

Alternative Methods

# pip
pip install uv

# pipx (recommended for pip installs)
pipx install uv

# Homebrew
brew install uv

# Cargo (builds from source, requires Rust toolchain)
cargo install --locked uv

Upgrading

# Self-update (standalone installer only)
uv self update

# Via pip
pip install --upgrade uv

Shell Autocompletion

# Bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

# Fish
echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish

Usage Examples

Quick Start — Create and Run a Project

# Create a new project
uv init my-app
cd my-app

# Add a dependency
uv add httpx

# Run the project
uv run python main.py

# Or run a specific command with extra dependencies
uv run --with ruff ruff check .

One-Off Tool Execution

# Run ruff without installing it (uvx is an alias for uv tool run)
uvx ruff check .

# Run a specific version
uvx ruff@0.6.0 check .

# Run with additional dependencies
uvx --with httpx==0.27.0 mytool

Managing Python Versions

# Install a specific Python version
uv python install 3.12

# Pin a version for the current project
uv python pin 3.12

# List installed versions
uv python list

Creating a Virtual Environment

uv venv --python 3.12
source .venv/bin/activate

Advanced Topics

Project Structure and Files: pyproject.toml, lockfiles, virtual environments → Projects

Managing Dependencies: Adding, removing, platform-specific deps, extras, dependency groups → Dependencies

Locking and Syncing: Lockfile management, upgrades, export formats, partial installations → Locking and Syncing

Running Commands: uv run, additional dependencies per invocation, scripts, signal handling → Running Commands

Workspaces: Multi-package monorepos, shared lockfiles, workspace sources → Workspaces

Tools Interface: uvx, tool install/upgrade, tool environments, per-invocation deps → Tools

Python Version Management: Managed vs system Python, .python-version files, installation → Python Versions

Configuration Files: pyproject.toml, uv.toml, environment variables, dotenv support → Configuration

Package Indexes: Private indexes, authentication, index strategies, pinning → Package Indexes

Caching: Cache semantics, clearing, CI caching, dynamic metadata → Caching

The pip Interface: uv pip install/compile/sync, environments, compatibility → pip Interface

Building and Publishing: uv build, uv publish, distribution formats → Build and Publish

CLI Reference: Command summary, common options, flags → CLI Reference