Skip to content

How to install uv

by Tim Hopper · Markdown
uv verified with uv 0.12

Install uv, the Python package and project manager, with the official standalone installer on macOS, Linux, or Windows. You don’t need Python installed first or administrator access. If you already use a package manager, see Choose the right install method.

Install with the standalone installer

Open a terminal, then run the install command. On macOS, that’s the Terminal app (press ⌘ Space, type Terminal, and press Return); on Linux, use your distribution’s terminal.

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

The installer prints its progress and finishes with everything's installed!.

Verify the installation

Close your terminal and open it again, then run:

uv --version

A successful install prints uv followed by its version number. If you get command not found or “uv is not recognized,” see Troubleshoot a failed installation. Restarting the terminal loads the updated PATH, the list of places it looks for commands.

Put uv to work

Choose the right install method

Use the standalone installer unless you already manage command-line tools with a package manager. Keep using that package manager to update uv, too.

Method Install command When to choose it
Homebrew (macOS/Linux) brew install uv You already use Homebrew.
WinGet (Windows) winget install --id=astral-sh.uv -e You manage Windows apps with WinGet.
Scoop (Windows) scoop install main/uv You already use Scoop.
pip pip install uv You need uv in an existing Python environment.
pipx pipx install uv You already manage Python command-line tools with pipx.

After installing, verify that uv runs. The pip and pipx methods require an existing Python installation; the standalone installer does not.

For CI or containers, use a guide for that environment: astral-sh/setup-uv for GitHub Actions or How to use uv in a Dockerfile for Docker. For other scripted installations, uv’s installer options cover version pinning and custom installation paths.

If you want to inspect the script first, follow uv’s installer inspection instructions. To install without running the script, choose a package manager from Choose the right install method or download a binary from uv’s GitHub releases.

Troubleshoot a failed installation

  • command not found after installing. The installer puts uv in ~/.local/bin (macOS/Linux) or %USERPROFILE%\.local\bin (Windows) and updates your PATH, but that change reaches only new sessions.

    • macOS/Linux: open a new terminal, or reload the current shell with source ~/.local/bin/env (fish: run the activation command printed by the installer).
    • Windows: close every terminal window and open a new one. A new Windows Terminal tab can inherit the old PATH, so a full restart is more reliable. To unblock the session you already have open, run $env:Path += ";$env:USERPROFILE\.local\bin".

    If it still fails, confirm the install directory is on your PATH.

  • curl is not installed. If wget is available, run wget -qO- https://astral.sh/uv/install.sh | sh. It prints installation progress and a success message.

  • Neither curl nor wget is installed. For a minimal container image, follow How to use uv in a Dockerfile. On a regular Linux system, install curl and CA certificates using your distribution’s package manager.

  • Windows blocks the script. The command in Install with the standalone installer passes -ExecutionPolicy ByPass so it runs under a restrictive policy. If you saved the script and run it as a file, pass the same flag: powershell -ExecutionPolicy ByPass -File uv-install.ps1.

  • You’re on WSL. Treat WSL as Linux: run the macOS / Linux command inside the WSL shell, not the Windows PowerShell installer.

  • You’re behind a proxy or offline. The installer fetches from astral.sh and github.com. Set https_proxy if you use one, or download a binary from uv’s GitHub releases and put it on your PATH.

  • uv self update won’t update. uv self-updates only binaries installed with the standalone installer. If you installed uv with Homebrew, WinGet, Scoop, pip, or pipx, upgrade it with that tool instead.

Find help for your platform

These guides cover shell completions, troubleshooting, and platform-specific details:

Uninstall uv

Follow uv’s uninstallation instructions to remove the binaries and optionally clear stored data. If you installed uv with a package manager, uninstall it with that manager.

This handbook is free, independent, and ad-free. If it saved you time, consider sponsoring it on GitHub.

Last updated on