Skip to content

How to install uv

by Tim Hopper · Markdown
uv verified with uv 0.12

The fastest way to install uv, the fast Python package and project manager, on macOS, Linux, or Windows is the official standalone installer. You don’t need Python installed already, and you don’t need administrator access. Other methods (pip, Homebrew, WinGet, Scoop) work too and are covered under 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

On Linux systems without curl, use wget:

wget -qO- https://astral.sh/uv/install.sh | sh

Either command prints its progress and finishes with a success line:

downloading uv 0.12.1 aarch64-apple-darwin
installing to /Users/you/.local/bin
  uv
  uvx
everything's installed!

To add $HOME/.local/bin to your PATH, either restart your shell or run:

    source $HOME/.local/bin/env (sh, bash, zsh)
    source $HOME/.local/bin/env.fish (fish)

Those last lines matter: the installer does not modify the current shell. Run the source line it prints, or open a new shell, before uv resolves.

Minimal images ship neither curl nor wget. In a debian:bookworm-slim shell both commands fail with command not found, so install one of them first along with the CA certificates the download needs:

apt-get update && apt-get install -y curl ca-certificates

That covers poking at a running container. For an image you build yourself, copy the uv binary from Astral’s published image instead of installing a downloader; see How to use uv in a Dockerfile.

After running the installer, open a new terminal window so your terminal can find the new uv command. (The installer adds uv to your PATH, the list of places your shell looks for programs, and that change reaches only new terminal sessions.)

The installer downloads a self-contained uv binary, so you don’t need Python installed first. uv can then install and manage Python interpreters for you.

Tip

To install a specific uv version for reproducible or scripted setups, put the version in the URL: curl -LsSf https://astral.sh/uv/0.12.1/install.sh | sh. Pass UV_NO_MODIFY_PATH=1 to run non-interactively without editing your shell profile.

Verify the installation 

uv --version

A successful install prints the version, the build commit, the build date, and the target triple on one line. If you get command not found, open a new terminal window so the updated PATH takes effect. If a new terminal doesn’t fix it, see Troubleshoot a failed installation.

What to do after installing uv

uv handles much more than package installation. With uv on your system, you can manage Python versions, create projects with lockfiles, run scripts with inline dependencies, and format code. The complete guide to uv walks through all of these workflows, or jump straight to creating your first Python project.

Choose the right install method

You’ve already installed uv the recommended way. Use a different method only if one of these fits your situation:

  • You already manage tools with Homebrew, WinGet, or Scoop. Installing uv there keeps it alongside your other packages, but uv self update won’t work; upgrade with the package manager instead (brew upgrade uv, for example).
  • You’re setting up CI. On GitHub Actions, the astral-sh/setup-uv action installs and caches uv (pin its version:). On GitLab CI, CircleCI, Jenkins, or any other runner, run the version-pinned standalone installer so builds are reproducible.
  • You’re building a container. Copy the uv binary from Astral’s published image instead of downloading it at build time; see How to use uv in a Dockerfile. If you do run the installer in a container, set UV_INSTALL_DIR to control where uv lands and UV_NO_MODIFY_PATH=1 to skip the shell-profile edit.
  • You want to run uv from an existing Python. pip install uv or pipx install uv works, though it ties uv to that interpreter.
Method Command
Standalone (macOS/Linux) curl -LsSf https://astral.sh/uv/install.sh | sh
Standalone (Windows) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Homebrew (macOS/Linux) brew install uv
WinGet (Windows) winget install --id=astral-sh.uv -e
Scoop (Windows) scoop install main/uv
pip pip install uv
pipx pipx install uv

Tip

Installing uv via pip or pipx creates a circular dependency (you need Python to install the tool that manages Python). The standalone installer avoids this.

Review the installer before running it

This step is optional. If you’re comfortable with the installation you just ran, skip to Troubleshoot a failed installation.

Piping a remote script directly to sh means you never see what it does before it runs. A malicious or compromised server could also detect the pipe and serve different content to curl | sh than to curl | less (see this 2018 demonstration).

If you want to read the installer before running it, download it to a file, review it, then execute it:

curl -LsSf https://astral.sh/uv/install.sh -o uv-install.sh
less uv-install.sh
sh uv-install.sh

To skip the install script entirely, use a package manager from Choose the right install method or download a signed binary from uv’s GitHub releases. Each release ships per-asset .sha256 files and a combined sha256.sum.

Every uv release also ships Sigstore/SLSA provenance attestations, so you can verify a downloaded binary was built by the official uv release workflow. With the GitHub CLI installed, pass the file you downloaded to gh attestation verify (uv-aarch64-apple-darwin.tar.gz on Apple Silicon, uv-x86_64-apple-darwin.tar.gz on an Intel Mac):

gh attestation verify uv-aarch64-apple-darwin.tar.gz --repo astral-sh/uv

For broader supply-chain defense, see How to protect against Python supply chain attacks with uv.

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: source ~/.config/fish/conf.d/uv.env.fish).
    • 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.

  • 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.

The platform-specific install guides cover shell completions and further troubleshooting.

Platform-specific guides

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

Frequently asked questions

Do you need Python to install uv?

No. The standalone installer downloads a self-contained uv binary and requires no existing Python interpreter, no package manager, and no other prerequisites. After installing uv, you can use uv python install to download a managed Python interpreter, or let uv init install a compatible one for you automatically.

What is uv?

uv is a fast Python package and project manager built by Astral (now part of OpenAI). It replaces pip, pip-tools, pipx, poetry, pyenv, and virtualenv with a single tool, and installs and resolves dependencies 10-100x faster than pip. See the uv reference page for full details.

How do I install uv on WSL?

Install uv the same way as on Linux. Run curl -LsSf https://astral.sh/uv/install.sh | sh inside your WSL shell, not the Windows PowerShell installer. WSL is a Linux system with its own filesystem and PATH, so the Windows binary won’t be on the path your WSL shell searches.

Can I install uv without admin rights?

Yes. The standalone installer places uv in ~/.local/bin (macOS/Linux) or %USERPROFILE%\.local\bin (Windows) without sudo or administrator rights. It does not write to system directories, so it works on locked-down and corporate machines.

How do I install uv with pip?

Run pip install uv. This works but is not recommended: you need a Python interpreter to install the tool that manages Python interpreters, creating a circular dependency. Use the standalone installer instead.

How do I update uv after installing it?

Run uv self update. This works for uv binaries installed with the standalone installer. If you installed uv through Homebrew, WinGet, or another package manager, use that package manager’s update command instead.

How do I install Python with uv?

Once uv is installed, run uv python install to download a managed Python interpreter, or run uv init in a project and uv will install a compatible Python automatically. See How to install Python with uv for details.

How do I uninstall uv?

Clear uv’s cache and managed directories, then delete the uv and uvx binaries:

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"
rm ~/.local/bin/uv ~/.local/bin/uvx

On Windows, delete uv.exe, uvx.exe, and uvw.exe from %USERPROFILE%\.local\bin. If you installed uv with a package manager, use that package manager to uninstall it instead.

Related

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

Last updated on
How to Install TritonGetting started with uv