uv 安裝指南
uv 安裝指南
簡介
什麼是 uv？
uv 是由 Astral 開發的新世代 Python 套件與專案管理工具，以 Rust 撰寫，目標是提供極速、可靠且統一的 Python 工作流程，能夠取代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等工具。
核心特性
- 極速安裝：效能遠超
pip與poetry，具備全域快取機制 - 一體化工具鏈：整合 Python 版本管理、虛擬環境、套件安裝與專案管理
- 相容 pip 介面：平滑銜接現有
pip使用習慣 - 跨平台支援：Windows、macOS、Linux 皆可使用
- 無需預先安裝 Python：uv 本身可直接下載並管理 Python 版本
安裝步驟
官方提供的 PowerShell 安裝腳本會自動下載 uv 的 Windows 二進位檔並設定好 PATH，是 Windows 環境下最快速的安裝方式。
開啟 PowerShell，執行以下指令：
1 | powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" |
安裝完成後，重新開啟終端機即可使用 uv 指令。
驗證安裝
安裝完成後，執行以下指令確認 uv 已正確安裝並顯示版本號：
1 | uv --version |
Python 版本管理
uv 內建 Python 版本管理功能，無需額外安裝 pyenv 或其他工具。
查看可用的 Python 版本
列出所有可下載與已安裝的 Python 版本：
1 | uv python list |
安裝指定的 Python 版本
安裝最新版本的 Python：
1 | uv python install |
安裝特定版本的 Python，例如 3.12：
1 | uv python install 3.12 |
若要安裝多個版本，可一次指定：
1 | uv python install 3.11 3.12 3.13 |
備註：uv 會將 Python 版本安裝至自身管理的目錄，不會影響系統原有的 Python 環境。
建立虛擬環境
在目前目錄下建立名為 .venv 的虛擬環境：
1 | uv venv |
若要指定 Python 版本建立虛擬環境：
1 | uv venv --python 3.12 |
啟用虛擬環境
建立完成後，執行以下指令啟用虛擬環境：
1 | .\.venv\Scripts\activate |
啟用後，終端機提示符前會出現 (.venv) 字樣，表示目前已在虛擬環境中運作。
可執行 python --version 確認虛擬環境使用的 Python 版本：
1 | python --version |
離開虛擬環境
作業完成後，執行 deactivate 即可退出虛擬環境，提示符前的 (.venv) 字樣將消失，回到系統原本的 shell 環境：
1 | deactivate |
升級 uv
透過 PowerShell 安裝腳本安裝的 uv，可使用內建的自我更新指令：
1 | uv self update |
啟用 Shell 自動補全
uv 支援 PowerShell 的指令自動補全功能，設定後輸入指令時可透過 Tab 鍵自動補全。
uv 指令補全
1 | Add-Content $PROFILE 'Invoke-Expression (& uv generate-shell-completion powershell | Out-String)' |
uvx 指令補全
1 | Add-Content $PROFILE 'Invoke-Expression (& uvx --generate-shell-completion powershell | Out-String)' |
設定完成後，請重新開啟終端機使其生效。
解除安裝
若需要從系統中完整移除 uv，請依照以下步驟操作。
步驟 1：清理 uv 儲存的資料（可選）
1 | uv cache clean |
步驟 2：移除二進位檔
1 | Remove-Item "$env:USERPROFILE\.local\bin\uv.exe" |
備註：0.5.0 之前的版本，預設安裝於
$env:USERPROFILE\.cargo\bin，升級至新版本時舊路徑下的二進位檔不會自動刪除，必要時需手動清理。
下一步
完成安裝並熟悉上述基礎指令後，建議繼續閱讀官方的 First Steps 教學，進一步了解如何使用 uv 管理專案依賴與發布套件：