uv 是 Astral 推出的 Python 工具鏈管理器，可以用來管理 Python 版本、虛擬環境、依賴、腳本、專案和工具。它的安裝方式很多，官方文件提供了獨立安裝腳本，也支援 PyPI、Homebrew、WinGet、Scoop、Docker、GitHub Releases 和 Cargo。

如果只是想快速安裝，優先使用官方獨立安裝腳本。如果你希望透過系統套件管理器維護版本，就用 Homebrew、WinGet 或 Scoop。如果你已經習慣用隔離方式安裝 Python 工具，可以用 pipx。

快速選擇

最推薦的通用方案：

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

1
2
3
4

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：

1
2
3
4

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

然後可以從幾個常見任務開始：

1
2
3
4

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，根據映像建置流程固定版本。

相關連結

• uv 安裝文件：https://docs.astral.sh/uv/getting-started/installation/
• uv First steps：https://docs.astral.sh/uv/getting-started/first-steps/
• uv Docker 整合：https://docs.astral.sh/uv/guides/integration/docker/
• uv GitHub Releases：https://github.com/astral-sh/uv/releases