uv

uv is a high-performance package and project manager from Astral that replaces pip, pip-tools, pipx, poetry, pyenv, and virtualenv with a single tool. The handbook covers installation on every platform, day-to-day workflows, migration from older tools, and the design choices that make it fast.

Get started with uv

Create your first project

Initialize a new Python project with uv

Install uv

Install uv on macOS, Linux, or Windows

Why try uv

What uv replaces and why it matters

pip-to-uv cheatsheet

Translate familiar pip commands to uv

Learn uv in depth

Complete Guide to uv

The full long-form walkthrough

pip vs uv

Compare features, speed, and workflows

uv vs Poetry

Two project managers, side by side

Migrate to uv

From Poetry

Move a Poetry project to uv

From requirements.txt

Adopt pyproject.toml with uv

From pyenv

Replace pyenv with uv for Python versions

More uv pages

Everything else tagged uv, grouped by section. Pages featured above are not repeated here.

Tutorial

Build a production Docker image for a uv project

Build production Docker images for uv projects. Multi-stage builds, layer caching, and bytecode compilation cut a FastAPI container from 306 MB to 223 MB.

Build a Python library with a C extension

Create a Python package that calls C functions using cffi and uv, with no prior C experience required.

Build a Python library with a C++ extension

Build Python packages with C++ extensions for performance-critical code. Learn pybind11, scikit-build-core, and uv for production deployment.

Build a Python library with a Rust extension

Create a Python package with Rust-powered functions. Use maturin as build backend, PyO3 to bridge Rust and Python, and uv for project management.

Build and Publish a Python Package with uv, Ruff, Pyrefly, pytest, and GitHub Actions

Build a Python library with uv, Ruff, Pyrefly, and pytest. Set up CI/CD with GitHub Actions. Publish to PyPI with trusted publishing.

Getting started with uv

Install uv, create a Python project, manage dependencies, run code, and switch Python versions in one tutorial.

Publishing Your First Python Package to PyPI

Publish a Python package to PyPI and TestPyPI using uv. Learn the workflow so anyone can install your code with pip.

Run your first Python script with uv

Create and run a Python script using uv, then add a third-party dependency with inline script metadata. No prior Python installation needed.

Set up a complete Python project with uv, Ruff, Pyrefly, pytest, and pre-commit

Tutorial: build a Python project from scratch with uv, Ruff, Pyrefly, pytest, and pre-commit. Set up linting, type checking, and testing.

Set up a data science project with uv

Set up data science with uv. Manage pandas, matplotlib, Jupyter, and reproducible environments—lockfiles included.

Set up a Django project with uv

Set up Django with uv. Skip manual Python setup; uv manages the interpreter, dependencies, and migrations from one command.

Set up a FastAPI project with uv

Set up FastAPI with uv. Create a project, add endpoints, test with pytest, lint with Ruff, and run in production, all from one tool.

Set up a multi-GPU training environment with uv

Create a distributed PyTorch training project with uv and Hugging Face Accelerate, then scale from one GPU to many without changing your training code.

Set up a Python project optimized for Claude Code

Build a Python CLI agent that understands your codebase and fixes bugs autonomously using Claude Code.

Setting up GitHub Actions with uv

Automate testing and linting on every push with GitHub Actions and uv. Run tests across multiple Python versions in CI.

Setting up testing with pytest and uv

Set up pytest with uv: project layout, parametrized tests, and coverage, so every contributor runs the same test suite.

Try Free-Threaded Python with uv

Install the free-threaded build of Python 3.14 with uv, run a CPU-bound threaded benchmark, and see real parallel speedup from lifting the GIL.

How To

How to Add a Dependency to a uv Project

Add a package to a uv project with uv add: it records the dependency in pyproject.toml and the lockfile so anyone who runs uv sync gets the same versions.

How to add dynamic versioning to uv projects

Auto-generate package versions from Git tags with uv. Stop manual version bumps: tag a commit and the wheel version updates automatically.

How to add Python to your system path with uv

Add uv-installed Python versions to your system PATH. Access multiple Python versions system-wide without virtual environments.

How to Build Read the Docs with uv

Configure Read the Docs to install dependencies with uv. Use dependency groups and lockfiles for reproducible builds.

How to Cache uv Dependencies in CI

Cache uv's package store and managed interpreters in CI to skip re-downloads, and keep .venv out so stale packages never survive a restore.

How to Cache uvx Tools in GitHub Actions

Stop uvx from re-downloading CLI tools on every CI run by keying the setup-uv cache to a pinned date instead of a lockfile.

How to change the Python version of a uv project

Set, change, upgrade, or downgrade the Python version of a uv project by pinning with `.python-version` and editing `pyproject.toml`.

How to Combine Coverage Across a CI Matrix

Aggregate coverage.py from GitHub Actions matrix jobs into one report, post to run summary, gate with single threshold.

How to configure Claude Code to use uv

Configure Claude Code to use uv without approval prompts. Set rules in CLAUDE.md and allow uv commands in .claude/settings.json.

How to configure Cursor for a uv project

Set up Cursor editor to work with a uv-managed Python project, including interpreter selection, Ruff formatting, pytest integration, and AI agent rules.

How to configure Cursor rules to use uv

Configure Cursor to use uv instead of pip. Let the AI agent install packages correctly with uv add and uv run.

How to Configure Helix for a uv Project

Set up Helix editor to work with a uv-managed Python project, including Ruff formatting, ty type checking, and virtual environment detection.

How to configure PyCharm for a uv project

Set up PyCharm to work with a uv-managed Python project: select the .venv interpreter, enable Ruff and pytest, and use the 2026.1.1 workspace beta.

How to configure VS Code for a uv project

Configure VS Code for uv projects: auto-detect the .venv interpreter, enable Ruff formatting, and run pytest without extra setup.

How to configure VS Code for type checking in a uv project

Set up type checking in VS Code for uv projects using ty or mypy extensions, including daemon mode and workspace diagnostics.

How to Configure Zed for a uv Project

Configure Zed editor for uv projects: virtual environment detection, Ruff formatting, basedpyright type checking, and task runner setup.

How to convert a script with requirements.txt to PEP 723 inline metadata

Move a one-off Python script's dependencies out of a sidecar requirements.txt and into a PEP 723 inline metadata block uv can read.

How to create a new Python project with Codex

Scaffold Python projects with Codex. Pipe the Modern Python Setup Guide URL and let Codex bootstrap the project.

How to create a pylock.toml lockfile

Generate PEP 751 pylock.toml with uv export, pip lock, or pdm export. Compare producers, pick the right one.

How to Create and Distribute a Python CLI Tool

Define a console_scripts entry point in pyproject.toml, publish to PyPI, and let users run your tool with uvx or uv tool install.

How to customize uv's virtual environment location

Override uv's default .venv location using UV_PROJECT_ENVIRONMENT environment variable or the --active flag to use an existing virtual environment.

How to Debug uv Dependency Resolution Failures

Fix uv resolution errors by reading the conflict chain, inspecting the dependency tree, and applying overrides or constraint narrowing.

How to deploy a uv project to AWS Fargate

Build a Fargate-ready container image with uv, match its CPU architecture, and cache uv downloads in an ECS build pipeline using Amazon ECR.

How to deploy a uv project to AWS Lambda

Package a uv project for AWS Lambda using container images, zip archives, or layers, with cross-platform builds and faster cold starts.

How to deploy a uv project to Azure Container Apps

Deploy a uv project to Azure Container Apps with buildpacks or Dockerfile. Cover zero-to-production quickly.

How to deploy a uv project to Fly.io

Deploy a uv-managed Python web app to Fly.io: a uv Dockerfile, binding to the port Fly routes to, fly launch, machine auto-stop, and secrets.

How to deploy a uv project to Google Cloud Run

Deploy a uv project to Cloud Run via source builds or a custom Dockerfile. Handle PORT and secrets management.

How to Deploy a uv Project to Hugging Face Spaces

Deploy a uv project to Hugging Face Spaces for a free, public app. Handles gradio integration and secrets.

How to deploy a uv project to Vercel

Deploy a uv project to Vercel with zero configuration. Vercel reads uv.lock natively for reproducible Python function installs.

How to distribute internal Python CLI tools with uv

Distribute internal Python CLI tools with uv: install from private index, git repo, or wheel. Pin versions, upgrade teams, bootstrap CI.

How to fix "No `project` Table Found" error in uv

Fix uv "No project table" error. Add minimal [project] metadata to pyproject.toml or use --no-project.

How to Fix "zsh: command not found: python" on macOS

Fix zsh: command not found: python on macOS by running python3 for a quick check or installing uv to manage Python and put it on PATH.

How to Fix Common pytest Errors with uv

Diagnose and fix ModuleNotFoundError, conftest issues, collection warnings, and other common pytest problems in uv-managed projects.

How to Fix pyenv's "No module named '_lzma'" Error

Fix a pyenv Python missing the lzma module by installing xz and rebuilding the interpreter, or skip source compilation with uv.

How to fix Python version incompatibility errors in uv

Fix Python version mismatches in uv. Align .python-version with requires-python to resolve uv compatibility errors quickly.

How to Ignore a Dependency in Dependabot Without Blocking Its Security Updates

Scope a Dependabot ignore rule to version updates so a pinned package stops routine PRs but still gets security fixes.

How to Install CUDA PyTorch Wheels Without a GPU

Declare the target CUDA driver version so uv resolves GPU PyTorch wheels on a build machine that has no GPU installed.

How to Install DeepSpeed

Install DeepSpeed from a prebuilt wheel on the Astral GPU index instead of compiling its CUDA ops from source.

How to Install Flash-Attention

Install Flash-Attention prebuilt wheels with uv to skip CUDA compilation. Route torch and flash-attn to GPU indexes for instant ML environment setup.

How to Install Hugging Face Transformers with uv

Install Hugging Face Transformers with uv for CPU inference, GPU training with CUDA, or quantized model loading with accelerate and bitsandbytes.

How to Install JAX with uv

Install JAX for CPU, NVIDIA GPU (CUDA 12/13), or Google TPU with uv. JAX uses pip extras; no custom index configuration needed.

How to install OpenAI's Astral plugins for Claude Code

Install OpenAI's Astral plugin for Claude Code. Get skills and a language server for uv, ruff, and ty with live type diagnostics.

How to Install Python (and Which Method to Choose)

Install Python with uv on macOS, Windows, or Linux, and let one tool manage versions so every project gets the right one.

How to install Python CLI tools without Python

Install any Python CLI tool (ruff, pytest, pre-commit) from PyPI without Python or uv using uvx.sh one-liners on macOS, Linux, or Windows.

How to Install Python on macOS

Install Python on macOS with uv instead of the system python3 or Homebrew, so pip stops failing and versions stay current.

How to Install Python on Windows

Install Python on Windows with uv or python.org. Stop the Microsoft Store from hijacking python and get a real interpreter on your PATH for development.

How to install Python with uv

Install and manage CPython interpreters with `uv python install`. No system Python or admin privileges required.

How to Install PyTorch with uv

Configure uv to install the correct PyTorch build for your hardware, whether you need CUDA, ROCm, or CPU-only wheels.

How to Install RAPIDS with uv

Configure uv to install NVIDIA RAPIDS libraries like cuDF and cuML with the correct CUDA version for your system.

How to install uv on 32-bit Raspberry Pi OS

Install uv on 32-bit Raspberry Pi OS, work around the libc detection and 32-bit-userland bugs, and configure piwheels for armv7l wheels.

How to install uv on Linux

Install uv on Linux with the standalone installer, Homebrew, or pip. Fast Python package manager with zero prerequisites.

How to install uv on macOS

How to install uv on macOS with the standalone installer, Homebrew, or pip. Covers Apple Silicon, PATH setup, and troubleshooting.

How to install uv on Windows

Install uv on Windows via PowerShell, WinGet, or Scoop. Fast Python package manager ready for development.

How to Keep a Capped Dependency from Blocking Dependabot Security Updates

Drop or raise a version ceiling in pyproject.toml so Dependabot can open security PRs instead of failing silently.

How to keep Python up to date with uv python upgrade

Run `uv python upgrade` to fetch the latest patch release for every uv-managed Python and have existing virtual environments follow.

How to lock uv script dependencies for reproducible execution

Use uv lock --script to pin a single-file script's dependencies and uv run --locked to enforce them in CI and shared automation.

How to maintain a uv project

Monthly maintenance checklist: automate Dependabot, uv audit, pre-commit auto-update, then do quarterly manual verification.

How to manage cross-repository Python dependencies with uv

Share packages across repos with uv. Use editable paths for development, git refs for pinning, [tool.uv.sources] to override sources.

How to Manage Environment Variables in a Python Project

Store secrets in a .env file, load them with uv run --env-file or python-dotenv, and keep them out of version control.

How to Measure Code Coverage with pytest-cov

Measure test coverage with pytest-cov and enforce minimum thresholds. Configure coverage reporting in pyproject.toml and integrate with CI pipelines.

How to Migrate from conda to uv

Convert a conda environment to a uv project with pyproject.toml and uv.lock for reproducible installs that finish in seconds.

How to migrate from Pipenv to uv

Convert a Pipenv project to uv by translating Pipfile to pyproject.toml and replacing Pipenv commands.

How to migrate from uv to pip

Move a uv-managed project to pip and pyenv (or python.org on Windows) by leaning on PEP 621, PEP 735, and PEP 751 in pyproject.toml.

How to Parameterize Tests with pytest

pytest.mark.parametrize: run same test logic across multiple inputs with custom IDs, stacked decorators, and indirect fixtures.

How to Protect Against Python Supply Chain Attacks with uv

Use uv's dependency cooldown to delay newly-published packages and its install-time malware check to block known-malicious versions before they run.

How to Publish to TestPyPI with uv

Upload a Python package to TestPyPI with uv to rehearse a PyPI release, then install it back to verify before pushing to the real index.

How to replace tox with uv and a Makefile

Replace tox with uv and Make for faster multi-Python testing. Parallel test runs with minimal configuration overhead.

How to Run a Jupyter Notebook with uv

Run Jupyter with uv: launch a temporary session with one command, or add it to a project for reproducible notebooks.

How to Run a Python REPL with uv

Start an interactive Python REPL with uv. Run with specific Python versions, add temporary packages, or skip project dependencies.

How to Run Parallel AI Coding Agents on One Python Project

Run multiple AI coding agents in parallel with git worktrees and isolated uv environments. Agents edit independently without conflicts.

How to run Python scripts on a Raspberry Pi with uv

Install uv on Raspberry Pi OS, then run Python scripts on a Pi without tripping the externally-managed-environment error.

How to Run Tests Using uv

Run pytest in uv-managed Python projects: filter tests, stop on failure, re-run failures, show output, and set persistent defaults.

How to run the IPython shell in your uv project

Run IPython in a uv project without modifying dependencies. Temporary sessions with --with or permanent dev dependency setup.

How to run uv on Modal

Build Modal images from a uv.lock with uv_sync, install ad-hoc packages with uv_pip_install, and run the synced environment on a GPU.

How to Serve LLMs Locally with vLLM and uv

Install vLLM with uv for local LLM serving and inference. NVIDIA CUDA GPU acceleration. OpenAI-compatible API endpoints.

How to set up a Python monorepo with uv workspaces

Configure uv workspaces to manage multiple Python packages in a single repository with shared dependencies and a unified lockfile.

How to Set Up CLAUDE.md for a Python Project

CLAUDE.md template for Python projects: configures Claude Code to use uv, Ruff, pytest, and modern Python tooling by default.

How to Test Against Multiple Python Versions Using uv

Test against Python 3.10–3.14 with one command via uv. Automatic interpreter downloads mean no manual version management.

How to Upgrade a Dependency Past Its Version Ceiling

Raise the version ceiling in pyproject.toml and force uv to re-lock so a capped dependency can move to its new major.

How to Upgrade Python Developer Tools

Stay current on Python developer tools: the right upgrade command depends on how each tool was installed.

How to upgrade setup-uv from v7 to v8

Migrate astral-sh/setup-uv from v7 to v8 in GitHub Actions, with SHA pinning for supply-chain security.

How to upgrade uv

Upgrade uv to the latest version. Get bug fixes and new features without downtime using uv self update or your package manager.

How to Use `--exclude-newer` for Reproducible Python Environments

Set uv's --exclude-newer to a date or a duration to rebuild an old environment exactly or keep brand-new releases out of a resolution.

How to use a uv lockfile for reproducible Python environments

Create, commit, refresh, and troubleshoot uv.lock so every machine and deployment installs identical dependency versions.

How to use free-threaded Python in a uv project

Install Python 3.14's free-threaded build, pin it in an existing uv project, and check whether your dependencies ship free-threaded wheels.

How to Use marimo with uv

Run marimo notebooks with uv: sandboxed PEP 723 notebooks, ad-hoc uvx sessions, and project environments.

How to use picamera2 and GPIO with uv on Raspberry Pi

Build a uv-managed environment on a Raspberry Pi that can import picamera2, libcamera, and gpiozero alongside pip-installed dependencies.

How to use pip in a uv virtual environment

Add pip to a uv virtual environment. Support Jupyter %pip magic and tools that require direct pip access.

How to Use Poe the Poet as a Task Runner with uv

Set up Poe the Poet as a task runner in uv projects. Define all development commands in pyproject.toml.

How to use private package indexes with uv

Configure uv for private registries (AWS CodeArtifact, Artifact Registry, Artifactory, Azure). Add indexes, auth, proxies, and TLS certs.

How to use uv in a Dockerfile

Build Docker images with uv for 10x faster builds. Layer caching and reproducible installs with uv.lock in containers.

How to use uv on NixOS

Install uv on NixOS, fix the dynamic-linker error that breaks managed Python downloads, and pin uv per project with a flake.nix dev shell.

How to Use uv on Windows ARM64

Install uv on Windows ARM64 and decide when to use native aarch64 Python instead of the default emulated x86_64 build.

How to use uv to speed up Hatch

Configure Hatch to use uv as its installer. Speed up environment creation 5-10x without changing Hatch workflows.

How to use uv to speed up PDM

Configure PDM to use uv as its resolver. Speed up dependency resolution 5-10x without changing your PDM workflow.

How to use uv to speed up tox

Install the tox-uv plugin to replace pip and virtualenv with uv, making tox environment creation and dependency installation 10-100x faster.

How to use uv with VS Code devcontainers

Configure a VS Code devcontainer with uv so a team shares the same Python environment from one lockfile.

How to Verify Dependencies with Hashes in uv

Verify uv dependencies with SHA-256 hashes. Detect tampering and cache corruption at install time to block compromised packages.

How to write install instructions for a Python library

Show readers (and their AI agents) how to install your library with uv, not just pip. The install snippet in your README is the first thing both will copy.

How to write self-contained Python scripts using PEP 723 inline metadata

Write self-contained scripts with PEP 723 metadata. Declare dependencies inline and run with `uv run` without a project.

Explanation

Can you trust uv long-term?

uv is VC-funded and Astral was acquired by OpenAI. The dual MIT / Apache license and a forkable codebase make uv a defensible long-term bet anyway.

Do I need a project to use uv?

uv works without a project directory. Here are options for using uv with single-file scripts, script collections, and when each approach makes sense.

Do you still need tox or nox if you use uv?

uv runs tests across Python versions, but tox and nox add dependency matrices, parallel execution, and session orchestration for complex test workflows.

Essential pytest Plugins

pytest plugins for reliable test suites: detect test-order bugs, kill hangs, retry flakes, and track performance regressions.

How do pyenv and uv compare for Python interpreter management?

pyenv focuses on Python version switching via shell shims, while uv integrates version management into a unified development toolkit.

How do uv and conda compare?

uv and conda solve different problems: uv installs PyPI wheels fast, conda manages cross-language binaries like CUDA and GDAL.

How do uv tool and pipx compare?

uv tool and pipx install Python CLI tools in isolated environments. uv is faster with better caching; pipx has more features. Compare for your use case.

How Python tools adopt uv under the hood

Hatch, PDM, pixi, tox, and other tools embed uv's resolver and installer as shared infrastructure, giving their users uv's speed without switching tools.

Modern Python Project Setup Guide for AI Assistants

Standardized instructions for AI assistants to scaffold modern Python projects using uv and pyproject.toml.

Running Python on Serverless

Compare Lambda, Cloud Run, Vercel, Modal, and other serverless platforms for uv projects. How uv and lockfiles change deployments.

Understanding dependency groups in uv

Dependency groups in uv organize project and dev dependencies. Learn how dependency groups, optional dependencies, and extras differ and when to use each.

uv for Non-Python Teams

Non-Python teams use Python for scripts and CLI tools. uv is the unified package manager, environment tool, and Python version tool for polyglot projects.

uv init: project types, flags, and examples

uv init creates a new Python project with a pyproject.toml and project scaffold. Covers --app, --lib, --no-package, --bare, and --python flags.

uv vs pixi vs conda for Scientific Python

Choosing between uv, pixi, and conda for scientific computing and GPU workloads depends on whether your dependencies live on PyPI, conda-forge, or both.

What Are uv Overrides and Constraints?

Control uv dependency resolution with overrides, constraints, and sources. Bypass version limits, enforce policies, or redirect package sources.

What Happens When You Run `uv run`

What happens when you run `uv run`: project discovery, Python resolution, environment creation, locking, syncing, and command execution in six stages.

What is a Dependency Cooldown?

A dependency cooldown ignores package versions published in the last few days, so malicious releases get caught before they reach your environment.

What Is an Editable Install?

An editable install links a package's source code to the Python environment so code changes take effect without reinstalling.

What is PEP 723?

Inline script metadata in Python files. PEP 723 lets uv, pipx, and other runners execute scripts with dependencies declared at the top.

When should I choose pixi over uv?

Pixi vs uv: Choose pixi for conda packages and native libraries (R, C++). uv for pure Python projects.

When to Use `uv run` vs `uvx`

Use uv run to execute project code with your dependencies; use uvx to run standalone tools in isolation without your project's dependencies.

Which Python package manager should I use?

A decision tree for choosing the right Python package manager based on your project type, team needs, and technical requirements.

Why did uv originally use Hatch as a build backend?

uv switched from Hatchling to uv_build backend. Why Hatchling was chosen first and why uv_build replaced it.

Why Doesn't the Authoritative Python Packaging Guide Mention the Best Thing that's Happened to Python Packaging?

The Python Packaging User Guide omits uv because PyPA only documents its own tools, despite uv's widespread adoption.

Why use native uv commands instead of uv pip

uv's native interface provides lockfiles, declarative dependencies, and automatic environments that uv pip alone cannot offer.

From the blog

Posts tagged uv.

Last updated on April 9, 2026