uv Installation Guide: Choosing Between macOS, Linux, Windows, pipx, Homebrew, and WinGet

Thu, 07 May 2026 23:23:58 +0800

uv is a Python toolchain manager from Astral. It can manage Python versions, virtual environments, dependencies, scripts, projects, and tools. There are many ways to install it. The official documentation provides standalone installer scripts and also supports PyPI, Homebrew, WinGet, Scoop, Docker, GitHub Releases, and Cargo.

If you just want a quick installation, use the official standalone installer first. If you prefer your system package manager to maintain versions, use Homebrew, WinGet, or Scoop. If you already like installing Python tools in isolated environments, use pipx.

Quick Choice

Scenario	Recommended method	Command
Quick install on macOS / Linux	Official standalone installer	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
macOS / Linux without curl	Official script + wget	`wget -qO- https://astral.sh/uv/install.sh \| sh`
Quick install on Windows	PowerShell installer	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`
Isolated Python tool install	pipx	`pipx install uv`
Temporary or traditional Python install	pip	`pip install uv`
macOS package management	Homebrew	`brew install uv`
macOS MacPorts users	MacPorts	`sudo port install uv`
Windows package management	WinGet	`winget install --id=astral-sh.uv -e`
Windows Scoop users	Scoop	`scoop install main/uv`
Rust users	Cargo	`cargo install --locked uv`

The generally recommended options are:

macOS / Linux: official standalone installer;
Windows: official PowerShell installer or WinGet;
If you already manage Python CLI tools with pipx: pipx install uv.

macOS and Linux: Official Installer

The most direct official method is to download the script with curl and run it with sh:

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

If the system does not have curl, use wget:

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

To install a specific version, put the version number in the URL. For example, the official example uses 0.11.11:

`1`	`curl -LsSf https://astral.sh/uv/0.11.11/install.sh \| sh`

This method fits most personal development environments. It is simple, cross-platform, and works best with uv’s official update mechanism.

The installer puts binaries such as uv and uvx under the user directory, and may modify the shell profile so the commands can be used directly in the terminal. If you do not want the installer to modify PATH, check the official installer options, such as setting UV_NO_MODIFY_PATH=1.

Windows: PowerShell Installer

The official Windows method is to run the installer script with PowerShell:

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`

To install a specific version, also put the version number in the URL:

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.11.11/install.ps1 \| iex"`

ExecutionPolicy ByPass allows PowerShell to fetch and run the installer script from the internet. As a safer habit, you can inspect the script before running it:

`1`	`powershell -c "irm https://astral.sh/uv/install.ps1 \| more"`

If you prefer Windows package managers, WinGet or Scoop may be a better first choice.

Installing with pipx

The official documentation notes that uv is published to PyPI. If you install from PyPI, it is recommended to put it in an isolated environment, for example with pipx:

`1`	`pipx install uv`

This is suitable if you already use pipx as your Python CLI tool manager. It avoids mixing uv with your current project environment.

If you do not have pipx, you can also use pip directly:

`1`	`pip install uv`

Note that uv provides prebuilt wheels on many platforms. If a platform does not have a matching wheel, it will build from source, which requires a Rust toolchain.

My suggestion: on a personal machine, pipx install uv is cleaner than pip install uv; inside a project environment, do not install uv as a project dependency.

Homebrew, MacPorts, WinGet, and Scoop

If you prefer system package managers, uv also supports common channels.

Use Homebrew on macOS:

`1`	`brew install uv`

MacPorts users can use:

`1`	`sudo port install uv`

Use WinGet on Windows:

`1`	`winget install --id=astral-sh.uv -e`

Scoop users can use:

`1`	`scoop install main/uv`

The benefit of these methods is that version maintenance is delegated to the system package manager. The downside is that update timing depends on the corresponding package source, not the uv official installer.

Docker, GitHub Releases, and Cargo

uv also provides Docker images on GitHub Container Registry:

`1`	`ghcr.io/astral-sh/uv`

This is suitable for CI, Dockerfiles, image builds, and temporary runtime environments. In real usage, read the official Docker integration documentation as well.

If you want to download binaries manually, use GitHub Releases. Each release page usually includes binaries for supported platforms and explains how to invoke the standalone installer with a GitHub URL.

Rust users can also install from crates.io:

`1`	`cargo install --locked uv`

This builds from source and requires a compatible Rust toolchain. Unless you specifically want to install from the Rust ecosystem, ordinary users do not need to choose Cargo first.

Upgrading uv

If uv was installed with the official standalone installer, use the self-update command:

`1`	`uv self update`

The official documentation notes that updating uv reruns the installer and may modify the shell profile. If you do not want the update to modify PATH, set:

`1`	`UV_NO_MODIFY_PATH=1`

If you installed uv another way, use the corresponding package manager. For example, if you installed it with pip, use:

`1`	`pip install --upgrade uv`

Homebrew, WinGet, Scoop, and MacPorts should also use their own upgrade commands.

Enabling Shell Completion

uv supports shell completion. The official documentation recommends checking your current shell first:

`1`	`echo $SHELL`

Bash:

`1`	`echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc`

Zsh:

`1`	`echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc`

fish:

`1`	`echo 'uv generate-shell-completion fish \| source' > ~/.config/fish/completions/uv.fish`

PowerShell:

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

If you often use uvx, you can enable completion for uvx separately.

Bash:

`1`	`echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc`

Zsh:

`1`	`echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc`

fish:

`1`	`echo 'uvx --generate-shell-completion fish \| source' > ~/.config/fish/completions/uvx.fish`

PowerShell:

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

After configuration, restart the shell or reload the corresponding configuration file.

Uninstalling uv

To uninstall uv, you can first clean the cache and uv-managed data:

1
2
3

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

Then delete the binaries.

macOS / Linux:

`1`	`rm ~/.local/bin/uv ~/.local/bin/uvx`

Windows:

1
2
3

rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe

The official documentation also notes that before 0.5.0, uv installed into ~/.cargo/bin. If you upgraded from an earlier version, old binaries may still be there and need to be removed manually.

What to Do After Installation

After installation, check the version first:

`1`	`uv --version`

Then start with a few common tasks:

uv python install
uv venv
uv pip install requests
uvx ruff --version

For a new project, continue with:

uv init: initialize a project;
uv add: add dependencies;
uv sync: sync the environment;
uv run: run commands inside the project environment;
uvx: run Python CLI tools temporarily.

My Recommendation

On a personal development machine, prefer the official standalone installer because it follows the uv official documentation most closely and supports uv self update.

Windows users who do not want to run a remote script can use WinGet or Scoop. macOS users who prefer managing all tools with Homebrew can directly use brew install uv.

If you already manage Python CLI tools with pipx, use pipx install uv. But I do not recommend installing uv with pip install uv inside a specific project virtual environment, because that tends to mix the toolchain with project dependencies.

For CI or container builds, start with Docker and GitHub Releases, and pin versions according to your image build process.

uv installation documentation: https://docs.astral.sh/uv/getting-started/installation/
uv First steps: https://docs.astral.sh/uv/getting-started/first-steps/
uv Docker integration: https://docs.astral.sh/uv/guides/integration/docker/
uv GitHub Releases: https://github.com/astral-sh/uv/releases

Package Management on KnightLi Blog