uv

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: curl -LsSf https://astral.sh/uv/install.sh | sh or pipx install uv. 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 Standalone installer (recommended — macOS/Linux)
• powershell -c "irm https://astral.sh/uv/install.ps1 | iex" Standalone installer (Windows)
• pipx install uv Via pipx (isolated, system-wide)
• pip install uv Via pip (not recommended — installs into current env)
• brew install uv Via Homebrew (macOS)

Imports

• uv (CLI)

  # 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

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 .