Astral uv 官方文件整理

uv 的主要功能和特點

uv 是由 Astral 公司（打造 Python Linter 工具 Ruff 的團隊）開發的一款高效能 Python 套件與環境管理工具，旨在以單一工具整合 Python 專案開發所需的多種功能。其主要特點包括：

• 一站式工具： uv 可以取代許多常用的 Python 工具，例如 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等 (uv)。也就是說，開發者只需安裝 uv，就能完成從套件安裝、虛擬環境管理、相依鎖定到專案發佈的所有工作。
• 極高速的效能： uv 由 Rust 實作，安裝套件的速度非常快，相較於傳統的 pip 可提升約 10～100 倍 (uv)。在處理相依解析、安裝等任務時，uv 能大幅縮短等待時間，提高開發效率。
• 完整的專案管理與鎖定檔： uv 提供如同 Poetry 等工具的專案管理功能，包括相依套件的新增、移除與鎖定檔（lockfile）生成。其鎖定檔為通用鎖定檔，可跨平台使用，確保不同作業系統下的環境一致性 (uv)。這讓專案在團隊協作或部屬時更具可重現性。
• 單檔腳本相依管理： uv 支援對單一 Python 腳本的相依管理。透過在腳本中加入特殊的註記或由 uv 自動維護的中繼資料，開發者可以用 uv add --script 宣告腳本所需的套件，之後執行 uv run 時會自動建立隔離的環境來執行該腳本 (uv) (uv)。這讓單檔腳本也能方便地管理所需套件，而不必手動建立虛擬環境。
• Python 多版本管理： uv 內建類似 pyenv 的功能，支援安裝和切換多個 Python 直譯器版本 (uv)。透過 uv python install <版本> 可以下載並安裝指定版本的 Python，使用 uv python pin <版本> 則能為當前專案目錄設定所需的 Python 版本。這讓在不同專案間切換 Python 版本變得簡單且一致。
• CLI 工具執行與安裝： uv 提供類似 pipx 的功能，可執行或安裝由 Python 套件提供的命令列工具 (uv)。例如使用 uvx <工具名> 可以在臨時環境中直接執行該工具（必要時自動安裝套件），或用 uv tool install <套件> 將工具安裝到全域環境中以後續重複使用 (uv)。
• 相容 pip 的介面： uv 附帶與 pip 幾乎相同的指令介面，開發者可以使用 uv pip install/uv pip sync/uv pip freeze 等指令來管理套件 (uv)。由於 uv 對這些常用指令作了效能優化與擴充，相依解析更聰明（支援版本覆寫、跨平台解析等）且速度更快，因此在不改變使用習慣的前提下享受顯著的性能提升 (uv)。
• 工作區與快取機制： uv 支援 Rust Cargo 風格的工作區 (workspace)，方便管理大型或多模組的專案 (uv)。另外，uv 採用全域共用的套件快取來節省磁碟空間，確保不同專案間相同版本的套件只下載與儲存一次，避免重複佔用空間 (uv)。
• 易於安裝、獨立執行： uv 本身編譯成可執行檔，不需要已安裝的 Python 或 Rust 環境即可使用 (uv)。官方提供的安裝腳本可直接下載對應平臺的 uv 執行檔，因此使用者無需自行編譯或滿足特定環境即可快速開始使用 uv。
• 跨平台支援： uv 完全支援在 macOS、Linux 和 Windows 等作業系統上運行 (uv)。這意味著無論是 Windows 開發者還是使用 Mac、Linux 的開發者，都可以在各自平臺獲得一致的體驗。官方將上述平臺列為一級支援，提供即時的測試與更新 (Platform support | uv)。

以上種種，使 uv 成為一個統一且高效的 Python 開發工具。開發者透過 uv 可以簡化開發流程，免去在不同工具間切換的繁瑣，同時獲得性能上的提升。

uv 與其他 Python 管理工具的比較

uv 試圖整合多種 Python 生態中的管理工具功能 (uv)。以下將 uv 與部分常見工具做比較，包括效能、用途與相容性等：

• pip： pip 是 Python 默認的套件安裝工具，只負責將套件安裝到目前環境中，本身不處理虛擬環境或相依鎖定。相比之下，uv 涵蓋 pip 的所有安裝功能且速度快上許多（官方測試顯示速度提升 10～100 倍） (uv)。此外，uv 每次 uv add 套件時會自動建立（或使用）專案的虛擬環境，避免污染全域環境。uv 也提供 uv pip ... 子命令來相容 pip 的用法 (uv)；也就是說，使用者可直接將原有的 pip 命令替換為 uv 執行，以獲得效能增益和進階功能，同時維持既有的工作流程 (uv)。
• pip-tools / pipenv： pip-tools 是用於產生和同步相依鎖定檔的工具（包含 pip-compile 和 pip-sync），pipenv 則結合了虛擬環境與相依管理。uv 的設計使其不再需要這些獨立工具：uv 自身即可解析專案的相依並產生通用的鎖定檔 uv.lock，確保不同平台下都能重現相同的套件組合 (uv)。透過 uv lock 和 uv sync 指令，uv 可以完成類似 pip-tools 的鎖定與環境同步功能。此外，uv 的相依解析演算法經過優化，可穩定且快速地計算相依關係，避免手動處理衝突。
• Poetry / Pipenv： Poetry 是另一個常用的專案管理工具，提供 pyproject.toml 相依定義和 poetry.lock 鎖定檔。uv 與 Poetry 類似之處在於都能管理專案相依與虛擬環境，不同的是 uv 更強調統一性與性能。uv 不僅能管理專案，相同工具還涵蓋了 Python 安裝和 CLI 工具執行等功能（這些是 Poetry 做不到的領域）。在效能上，uv 由於採用 Rust 編寫，操作大型專案時解析和安裝速度更快。事實上，uv 的目標之一是成為 Python 生態的「Cargo」 (Python包管理不再头疼：uv工具快速上手- wang_yb - 博客园) ，提供類似 Rust Cargo 那樣的工作區管理和發行流程。對於已熟悉 Poetry 的使用者，uv 也能順利接手現有專案：uv 支援讀取 pyproject.toml 並可匯入現有的相依設定，讓遷移過程平滑。
• pyenv： pyenv 用於在一台機器上安裝多個 Python 版本並快速切換。uv 將這項功能內建在 uv python 指令組中 (uv)。使用 uv，開發者無需另裝 pyenv，即可列出可用的 Python 版本、下載安裝指定版本，並且快速在專案中設定使用特定的 Python 版本（透過生成 .python-version 檔案來鎖定）。因此，uv 大幅簡化了 Python 版本管理的流程，而且不同於 pyenv 只管理版本，uv 還能在安裝時自動抓取對應版本的 Pip 等附屬工具，使環境更完整。
• virtualenv： virtualenv 或 Python 內建的 venv 模組用於建立隔離的虛擬環境。uv 在套件管理時自動處理虛擬環境的建立與使用 (uv)。例如第一次在專案目錄執行 uv add 套件時，uv 會自動創建一個 .venv 虛擬環境並將套件安裝其中 (uv)。開發者無需手動執行 python -m venv 或 activate 等步驟，減少了環境設定的麻煩。換句話說，uv 本身就包含了 virtualenv 的功能，而且還加入了全域快取來避免不同虛擬環境間重複安裝套件 (uv)。
• pipx： pipx 專注於將 Python 套件作為獨立的終端工具安裝並隔離執行。uv 提供了對等的解決方案：使用 uvx 可以臨時執行尚未安裝的 CLI 工具命令，uv 會自動下載並在隔離環境執行該工具；而使用 uv tool install 可以將這些命令列工具安裝到環境中供全域使用 (uv)。因此，uv 可完全取代 pipx，並且由於使用相同的全域快取機制，重複使用工具時不需要每次重新下載所需套件。
• Twine： Twine 是用於將套件發佈到 PyPI 等套件索引庫的工具。uv 也內建了套件建構與發佈功能。例如開發者可以使用 uv build 來建置專案的發行套件（wheel 檔案等），並透過 uv publish 或相關指令將套件上傳至指定的套件庫，功能上相當於整合了 Twine (uv)。這使得 uv 不僅能管理開發時的環境與相依，也涵蓋了專案發布流程，真正做到從開發到部署的一條龍服務。

總而言之，uv 的優勢在於整合與性能：只需此一工具便覆蓋了上述各種工具的功能，減少學習成本和環境設定的複雜度。同時，由於 uv 經過優化的實作，在各項操作上的效率明顯優於傳統工具，這對需要經常安裝大量套件或處理大型專案的開發者而言是極大的助益。

uv 的安裝方式與基本使用範例

安裝方式：uv 提供多種安裝管道，使用者可依偏好選擇：

• 官方安裝腳本： 這是最簡單的方式。對於 macOS 和 Linux 系統，可直接使用 curl 下載並執行安裝腳本；Windows 系統則提供對應的 PowerShell 腳本 (uv)。例如：

  
  $ curl -LsSf https://astral.sh/uv/install.sh | sh    # macOS/Linux
        

  
  PS> irm https://astral.sh/uv/install.ps1 | iex       # Windows PowerShell
        

  上述腳本會自動下載適用於該平臺的 uv 可執行檔並完成安裝。由於 uv 為獨立執行檔，不需要先安裝 Python 或 Rust 即可使用 (uv)。安裝完成後，可直接在命令列輸入 uv --version 驗證是否安裝成功。
• 使用套件管理工具： 如果偏好透過現有的套件管理系統安裝，uv 也可以從 PyPI 安裝（例如使用 pipx install uv 或 pip install uv） (Installation | uv)、或使用 Homebrew（macOS）安裝 brew install uv (Installation | uv)。在 Windows 上，Microsoft Store 的 WinGet 以及第三方套件管理器 Scoop 亦提供了 uv（如 winget install astral-sh.uv 或 scoop install uv） (Installation | uv)。透過這些系統安裝時，建議使用 pipx 或隔離環境，避免將 uv 綁定在某個特定的 Python 環境中運行 (Installation | uv)。
• 其他安裝途徑： 進階用戶也可以選擇透過 Cargo （Rust 的套件管理工具）從原始碼構建並安裝 uv (Installation | uv)，或直接從 Docker Hub 取得官方提供的 uv Docker 映像 (Installation | uv)。此外，GitHub Releases 頁面也提供各平臺的壓縮包下載，方便在無網路安裝腳本環境下手動安裝。

基本使用範例： 安裝完成 uv 後，即可開始使用其強大功能。以下透過建立一個新專案並安裝套件的步驟，展示 uv 的基本用法：

1. 初始化專案： 使用 uv init <專案名稱> 指令建立新專案目錄。例如：uv init demo-project。執行後，uv 會在當前路徑下建立名為 demo-project 的資料夾，其中包含預設的專案配置檔案（如 pyproject.toml）和空的虛擬環境目錄。
2. 安裝套件依賴： 進入專案目錄（cd demo-project），然後使用 uv add <套件名稱> 安裝所需的套件。舉例而言，安裝 Python 靜態檢查工具 ruff：執行 uv add ruff。首次執行時，uv 會自動建立虛擬環境（預設位於專案的.venv目錄） (uv)，解析並安裝 ruff 及其相依套件。過程中可以看到 uv 列出解析所花費的時間及安裝的套件列表，安裝完成後 .venv 中已包含 ruff 套件 (uv)。
3. 執行命令或腳本： 套件安裝後，可以透過 uv 執行相關命令。例如剛安裝的 ruff 提供了 ruff 終端命令，可使用 uv run ruff --version 來檢視版本，或執行 uv run ruff check . 對專案進行代碼檢查 (uv)。uv run <command> 會在專案的虛擬環境中執行指定命令，確保使用正確的 Python 版本和已安裝的套件。類似地，也可以執行自訂的 Python 腳本，例如 uv run main.py（若腳本有相依需求，uv 會自動安裝缺少的套件）。
4. 鎖定與同步相依： 當專案相依安裝完畢並測試無誤後，建議執行 uv lock 產生或更新鎖定檔（通常命名為 uv.lock） (uv)。鎖定檔會記錄當前所有相依套件的精確版本，以備團隊其他成員或部署時重現相同環境。之後，如需在其他環境重現或更新本專案的環境，使用 uv sync 指令即可根據鎖定檔安裝相依套件，讓環境與鎖定檔同步 (uv)。

以上是一個完整的專案循環的基本操作流程。透過 uv，從初始化專案、安裝套件到執行與鎖定，都可以在一套工具內完成，且速度快且順暢。除了專案場景，uv 也能便利地處理其他使用情境，例如單一腳本的相依管理和命令列工具安裝：

• 若要在單個 Python 檔案中定義相依，可以在腳本檔中加入相依註記（uv 會自動維護該資訊），並使用 uv add --script <檔案名> <套件> 新增所需套件 (uv)。之後直接 uv run <檔案名>，uv 將檢查並安裝缺少的相依，再執行該腳本 (uv)。這種方式適用於撰寫小型腳本或工具時快速解決套件相依問題。
• 若想執行尚未安裝的 CLI 工具，可以使用 uvx <工具命令>。例如：uvx pycowsay "Hello"，uv 會在臨時環境下載並執行 pycowsay 套件的指令 (uv)。而使用 uv tool install <套件> 則會將這些命令列工具安裝到使用者環境路徑中，之後可直接呼叫（類似 pipx 的功能） (uv)。

透過以上例子可以看出，uv 的操作與傳統工具相比更加簡潔：無需手動創建或啟用虛擬環境，也不必分開執行 pip/venv/pyenv 等多種指令。這對於習慣在專案中頻繁安裝測試套件、或管理多個腳本和工具的開發者來說，大大提升了體驗的一致性和便利性。

uv 支援的作業系統與平台

uv 是一款跨平臺的工具，官方提供對多種作業系統及平台的支援：

• Windows： 支援 Windows 10（含）以上版本的作業系統（x86_64 架構） (Platform support | uv)。官方提供可執行檔與安裝腳本相容於此平臺，確保 Windows 用戶能順利使用 uv 的全部功能。
• macOS： 同時支援 macOS Intel x86_64 與 Apple Silicon (ARM64) 架構的系統 (Platform support | uv)。無論是傳統的 Intel Mac 還是 M1/M2 系列的 Apple Silicon Mac，都有對應的 uv 版本進行優化與測試。
• Linux： 對常見的 Linux 發行版（x86_64 架構）提供一級支援與預先編譯的二進位發行 (Platform support | uv)。此外，uv 也能在其他架構的 Linux 平台上編譯使用，例如 ARM64 (aarch64)、Armv7、PowerPC 等 (Platform support | uv)。官方將這些非 x86_64 平台列為二級支援，提供預建的軟體套件（wheel 檔） (Platform support | uv)，雖然這些版本未像一級平臺般經過完整的持續測試，但一般使用情境下依然可以正常運行。

從官方資訊來看，uv 已對主流的桌面與伺服器環境做了廣泛的相容性考量 (Platform support | uv)。使用者只需選擇對應作業系統的安裝方式即可開始使用 uv。而在 Python 版本方面，uv 支援並經過測試的 Python 版本涵蓋 3.8 到 3.13，確保使用 uv 管理這些版本的環境和套件時都能正常運作 (Platform support | uv)。這種廣泛的平臺與版本支援，使 uv 成為各種開發環境下可靠的 Python 工具。

參考資料：

• Astral 官方 uv 文件： (uv) (uv) (uv) (Platform support | uv) (Platform support | uv)等。如需更詳細的指令說明與範例，建議閱讀 uv 的官方文件和指南。