uv 安裝指南：macOS、Linux、Windows、pipx、Homebrew 和 WinGet 怎麼選

Thu, 07 May 2026 23:23:58 +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，根據映像建置流程固定版本。

Astral on KnightLi的博客