uv 安装指南：macOS、Linux、Windows、pipx、Homebrew 和 WinGet 怎么选

Thu, 07 May 2026 23:02:49 +0800

uv 是 Astral 推出的 Python 工具链管理器，可以用来管理 Python 版本、虚拟环境、依赖、脚本、项目和工具。它的安装方式很多，官方文档提供了独立安装脚本，也支持 PyPI、Homebrew、WinGet、Scoop、Docker、GitHub Releases 和 Cargo。

如果只是想快速安装，优先用官方独立安装脚本。如果你希望通过系统包管理器维护版本，就用 Homebrew、WinGet 或 Scoop。如果你已经习惯 Python 工具隔离安装，可以用 pipx。

快速选择

场景	推荐方式	命令
macOS / Linux 快速安装	官方独立安装脚本	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
macOS / Linux 没有 curl	官方脚本 + wget	`wget -qO- https://astral.sh/uv/install.sh \| sh`
Windows 快速安装	PowerShell 安装脚本	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`
Python 工具隔离安装	pipx	`pipx install uv`
临时或传统 Python 安装	pip	`pip install uv`
macOS 包管理	Homebrew	`brew install uv`
macOS MacPorts 用户	MacPorts	`sudo port install uv`
Windows 包管理	WinGet	`winget install --id=astral-sh.uv -e`
Windows Scoop 用户	Scoop	`scoop install main/uv`
Rust 用户	Cargo	`cargo install --locked uv`

最推荐的通用方案：

macOS / Linux：官方独立安装脚本；
Windows：官方 PowerShell 安装脚本或 WinGet；
已经使用 pipx 管理 Python CLI 工具：pipx install uv。

macOS 和 Linux：官方安装脚本

官方最直接的安装方式是用 curl 下载脚本并交给 sh 执行：

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

如果系统没有 curl，可以用 wget：

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

如果想安装指定版本，可以把版本号放进 URL。比如官方示例中的 0.11.11：

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

这个方式适合绝大多数个人开发环境。它的优点是简单、跨平台、和 uv 官方更新机制配合最好。

安装脚本会把 uv、uvx 等二进制文件安装到用户目录下，并可能修改 shell profile，让命令可以直接在终端中使用。如果你不希望安装器修改 PATH，可以参考官方 installer 选项，例如设置 UV_NO_MODIFY_PATH=1。

Windows：PowerShell 安装脚本

Windows 官方安装方式是用 PowerShell 执行安装脚本：

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

如果要安装指定版本，也可以把版本号放进 URL：

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

这里的 ExecutionPolicy ByPass 是为了允许从互联网获取并执行安装脚本。安全习惯上，执行前可以先查看脚本内容：

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

如果你习惯 Windows 包管理器，也可以优先用 WinGet 或 Scoop。

用 pipx 安装

官方文档提到，uv 发布到了 PyPI。如果从 PyPI 安装，推荐放进隔离环境，例如用 pipx：

`1`	`pipx install uv`

这个方式适合已经把 pipx 当作 Python CLI 工具管理器的人。它可以避免把 uv 和当前项目环境混在一起。

如果没有 pipx，也可以直接用 pip：

`1`	`pip install uv`

但要注意：uv 在许多平台上提供预构建 wheel。如果某个平台没有对应 wheel，就会从源码构建，这时需要 Rust 工具链。

我的建议是：个人机器上，pipx install uv 比 pip install uv 更干净；项目环境里，不建议把 uv 当作项目依赖安装。

Homebrew、MacPorts、WinGet 和 Scoop

如果你更喜欢系统包管理器，uv 也支持常见渠道。

macOS 上用 Homebrew：

`1`	`brew install uv`

MacPorts 用户可以用：

`1`	`sudo port install uv`

Windows 上用 WinGet：

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

Scoop 用户可以用：

`1`	`scoop install main/uv`

这些方式的好处是统一交给系统包管理器维护。缺点是升级节奏取决于对应包源，而不是 uv 官方安装脚本。

Docker、GitHub Releases 和 Cargo

uv 还提供 Docker 镜像，地址在 GitHub Container Registry：

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

这适合 CI、Dockerfile、构建镜像和临时运行环境。实际使用时，建议再看官方 Docker 集成文档。

如果你想手动下载二进制文件，可以从 GitHub Releases 获取。每个 release 页面通常包含支持平台的二进制文件，也会说明如何用 GitHub 地址调用独立安装器。

Rust 用户也可以从 crates.io 安装：

`1`	`cargo install --locked uv`

但这个方式会从源码构建，需要兼容的 Rust 工具链。除非你明确需要从 Rust 生态安装，否则普通用户不必优先选 Cargo。

升级 uv

如果 uv 是通过官方独立安装脚本安装的，可以用自更新命令：

`1`	`uv self update`

官方提示说，更新 uv 会重新运行安装器，并可能修改 shell profile。如果不希望更新时修改 PATH，可以设置：

`1`	`UV_NO_MODIFY_PATH=1`

如果你是通过其他方式安装的，就应该用对应包管理器升级。比如用 pip 安装，就用：

`1`	`pip install --upgrade uv`

Homebrew、WinGet、Scoop、MacPorts 也应该走各自的升级命令。

启用 shell 自动补全

uv 支持 shell 自动补全。官方文档建议先用下面命令确认当前 shell：

`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'

如果你也经常用 uvx，可以单独启用 uvx 补全。

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'

配置后需要重启 shell，或者重新加载对应配置文件。

卸载 uv

如果要卸载 uv，可以先清理缓存和 uv 存储的数据：

1
2
3

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

然后删除二进制文件。

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

官方文档还提醒：0.5.0 之前，uv 会安装到 ~/.cargo/bin。如果你从早期版本升级过，旧二进制文件可能仍然留在那里，需要手动删除。

安装后先做什么

安装完成后，建议先确认版本：

`1`	`uv --version`

然后可以从几个常见任务开始：

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

如果你是新项目，可以进一步学习：

uv init：初始化项目；
uv add：添加依赖；
uv sync：同步环境；
uv run：在项目环境中运行命令；
uvx：临时运行 Python CLI 工具。

我的建议

个人开发机上，优先使用官方独立安装脚本，因为它最贴近 uv 官方文档，也支持 uv self update。

Windows 用户如果不想执行远程脚本，可以用 WinGet 或 Scoop。macOS 用户如果习惯所有工具都交给 Homebrew 管理，可以直接 brew install uv。

已经使用 pipx 管理 Python CLI 工具的人，可以用 pipx install uv。但不建议在具体项目虚拟环境里用 pip install uv，这样容易把工具链和项目依赖混在一起。

如果是 CI 或容器构建，优先看 Docker 和 GitHub Releases，根据镜像构建流程固定版本。

包管理 on KnightLi的博客