uv

0.11.2 verified Tue May 12 auth: no python install: verified quickstart: stale

Extremely fast Python package and project manager written in Rust by Astral. Current version is 0.11.2 (Mar 2026). Replaces pip, pip-tools, pipx, poetry, pyenv, virtualenv, and twine in a single tool. Recommended install is the standalone installer or pipx — NOT pip install uv into a project venv. uv is a CLI tool, not a Python library to import.

pip install uv

Common errors

error uv: command not found ↓

cause The 'uv' executable is not installed or its installation directory is not included in your system's PATH environment variable.

fix

Install uv using the standalone installer (e.g., curl -LsSf https://astral.sh/uv/install.sh | sh for Unix-like systems) or pipx install uv, and ensure the installation directory (e.g., ~/.cargo/bin or ~/.local/bin) is added to your system's PATH.

error ModuleNotFoundError: No module named 'uv' ↓

cause `uv` is a standalone command-line interface (CLI) tool, not a Python library intended for direct import within Python scripts.

fix

Use uv directly from your terminal or command prompt. Do not attempt to import uv in Python code.

error Failed to find a Python interpreter ↓

cause `uv` could not locate a Python interpreter in your system's PATH or through common Python version managers (like pyenv, asdf, or conda), which is necessary for creating and managing virtual environments.

fix

Ensure a Python interpreter is installed and its location is included in your system's PATH. Alternatively, specify the Python interpreter explicitly using uv venv --python python3.10 or uv python --version 3.10.

error `'uv' is not recognized as an internal or external command, operable program or batch file.` ↓

cause On Windows, the 'uv' executable is not installed or its directory is not added to the system's PATH environment variable.

fix

Install uv using the standalone installer (download from astral.sh/uv) or pipx install uv. After installation, ensure the directory containing uv.exe (often C:\Users\<YourUser>\.cargo\bin or C:\Users\<YourUser>\AppData\Roaming\Python\Scripts) is added to your system's PATH.

Warnings

gotcha pip install uv into a project venv is not recommended. uv is a system-level tool — installing it as a project dependency is unnecessary and can cause version conflicts. Use the standalone installer or pipx. ↓

fix Install globally by running "curl -LsSf https://astral.sh/uv/install.sh | sh" directly in your shell, or use "pipx install uv". If executing this from a Python script, use the subprocess module (e.g., subprocess.run(["sh", "-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"])) to run shell commands. Only use pip install uv in CI/Docker where you need a quick install without curl.

gotcha uv pip install and uv add are different commands. uv pip install is a pip drop-in — it installs into the current environment without writing to pyproject.toml or lockfile. uv add is the project-aware command that updates pyproject.toml and uv.lock. ↓

fix For project dependencies: use uv add requests. For quick pip-compatible installs: use uv pip install requests. Never mix them in the same workflow.

gotcha uv run automatically creates a virtual environment in .venv if one doesn't exist. Running uv run before uv sync in CI can produce an environment with only default dependencies, missing project extras. ↓

fix In CI: run uv sync first, then uv run. Or use uv run --frozen to prevent environment creation if the lockfile is not satisfied.

breaking TLS certificate verification changed in 0.11.1: rustls-platform-verifier replaced rustls-native-certs for certificate validation. May reject certificates previously trusted, especially on systems with custom CA certificates. ↓

fix If you see TLS certificate errors after upgrading, use UV_NATIVE_TLS=1 environment variable or --native-tls flag to fall back to system TLS.

gotcha uvx is an alias for uv tool run — it runs tools in ephemeral, isolated environments. Tools installed with uv tool install persist. uvx installs and runs in a throwaway env each time. ↓

fix For one-off use: uvx ruff check . For permanent install: uv tool install ruff then ruff check .

gotcha uv generates uv.lock (not requirements.txt or poetry.lock). The lockfile is universal — it contains dependencies for all platforms. Committing uv.lock to version control is required for reproducible builds. ↓

fix Always commit uv.lock. In CI, use uv sync --frozen to install exactly what's in the lockfile without updating it.

Install

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

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

pipx install uv

brew install uv

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - 18.5M

3.10 slim (glibc) - - - 19M

3.11 alpine (musl) - - - 20.4M

3.11 slim (glibc) - - - 21M

3.12 alpine (musl) - - - 12.2M

3.12 slim (glibc) - - - 13M

3.13 alpine (musl) - - - 11.9M

3.13 slim (glibc) - - - 12M

3.9 alpine (musl) - - - 18.0M

3.9 slim (glibc) - - - 19M

Imports

uv (CLI)

wrong

# uv is NOT a Python library:
import uv  # ModuleNotFoundError
from uv import install  # ModuleNotFoundError

correct

# uv is a CLI tool — not a Python library to import
# Key commands:

# Project management
uv init myproject          # create new project
uv add requests            # add dependency
uv remove requests         # remove dependency
uv sync                    # install all deps from lockfile
uv run python script.py    # run in project venv
uv run pytest              # run tool in project venv

# Python management
uv python install 3.12     # download and install Python
uv python pin 3.12         # pin version for current dir

# pip compatibility mode
uv pip install requests    # fast pip replacement
uv pip install -r requirements.txt

# Tool runner (like pipx)
uvx ruff check .           # run ruff in ephemeral env
uvx black .                # run black without installing

uv is a command-line tool only — there is no Python API to import. It manages packages, venvs, Python versions, and scripts from the terminal.

Quickstart stale last tested: 2026-04-23

uv init creates pyproject.toml. uv add writes deps + lockfile. uv run uses the project venv.

# Install uv (standalone installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new project
uv init myapp
cd myapp

# Add dependencies (writes to pyproject.toml + uv.lock)
uv add fastapi uvicorn pydantic
uv add --dev pytest ruff black

# Run the project
uv run uvicorn main:app --reload

# Run tests
uv run pytest

# Sync environment from lockfile (like pip install -r)
uv sync

# Install a specific Python version
uv python install 3.12
uv python pin 3.12  # pins .python-version

# pip compatibility (drop-in for pip)
uv pip install requests
uv pip install -r requirements.txt
uv pip compile requirements.in  # like pip-tools

# Run tools without installing (like pipx run)
uvx ruff check .
uvx black .