• 官方文檔：https://docs.astral.sh/uv/
• 中文文檔：https://uv.doczh.com/
• GitHub地址：https://github.com/astral-sh/uv

1. UV 介紹

UV 是一個由 Astral 公司用 Rust 開發的高性能 Python 包管理工具，旨在提供比傳統 pip 更快的包安裝和依賴管理體驗。

An extremely fast Python package and project manager, written in Rust.

Python 生態系統中的包管理一直是開發者關注的焦點。從最初的 pip 到后來的 Poetry、PDM 等工具，每一次演進都試圖解決前代工具的痛點。而今天我們要介紹的 UV，作為由 Ruff 團隊（Astral）開發的下一代 Python 包管理工具，正以其驚人的速度和創新的設計理念，重新定義 Python 包管理的標準。

1.1 什么是UV？

UV 是一個極速的 Python 包管理器和解析器，由 Rust 編寫，專注于提供卓越的性能和用戶體驗。其名稱 “UV” 源自 “μv”（微伏），暗示著其輕量級和高效的特性。作為 pip 的直接替代品，UV 提供了兼容的命令行接口，同時在速度上實現了數量級的提升。

1.2 UV的核心優勢

與傳統的 Python 包管理工具相比，UV 具有以下顯著優勢：

• 🚀 一體化工具：一個工具替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等多種工具
• ?? 極致速度：比 pip 快 10-100 倍
• 🗂? 全面項目管理：提供通用鎖文件的綜合項目管理功能
• ?? 腳本運行：支持帶有內聯依賴元數據的腳本運行
• 🐍 Python版本管理：安裝和管理不同的 Python 版本
• 🛠? 工具安裝：運行和安裝以 Python 包形式發布的工具
• 🔩 兼容pip接口：提供熟悉的命令行界面，同時大幅提升性能
• 🏢 工作區支持：支持 Cargo 風格的工作區，適用于大規模項目
• 💾 高效磁盤空間利用：通過全局緩存實現依賴去重
• ? 簡易安裝：無需 Rust 或 Python 環境，可通過 curl 或 pip 直接安裝
• 🖥? 多平臺支持：支持 macOS、Linux 和 Windows 系統

隨著Python項目規模和復雜度的增長，傳統工具在性能和用戶體驗方面的局限性日益凸顯。UV 的出現，為開發者提供了一個更快、更可靠的選擇，特別適合大型項目和CI/CD環境中的應用。

1.3 UV和其他工具對比

在Python生態系統中，包管理和環境管理工具眾多，主要包括pip+virtualenv、Poetry、Conda等。在決定是否采用UV之前，了解它與現有工具的區別和優勢非常重要。

1）UV vs. pip+virtualenv

pip和virtualenv是Python包管理和虛擬環境創建的傳統工具組合。UV相比它們具有以下優勢：

• 速度：UV的Rust實現使其比pip快10-100倍，特別是在大型項目中
• 集成環境管理：UV將包管理和環境管理集成在一個工具中，簡化了工作流程
• 內存使用：UV在包安裝和依賴解析過程中使用的內存顯著減少
• 錯誤處理：UV提供更清晰的錯誤信息和更好的依賴沖突解決方案
• 可復現性：UV的鎖文件方法確保了跨系統環境的一致性，這是基本requirements.txt文件無法保證的

2）UV vs. Conda

Conda是一個完整的包管理解決方案，特別適合科學計算環境。UV與Conda相比：

• 速度：UV的包安裝和依賴解析速度遠快于Conda的有時緩慢的性能
• 資源占用：UV具有更小的資源占用，意味著更少的內存使用和更快的啟動時間
• 集成性：UV與現有Python打包標準和工具無縫集成，更容易與更廣泛的Python生態系統協作
• 非Python包：Conda可以管理非Python包和系統級依賴，而UV專注于Python包

3）UV vs. Poetry

Poetry是另一個現代Python項目管理工具，與UV有許多相似之處：

• 依賴管理：兩者都有效處理包依賴和虛擬環境
• 項目結構：兩者都提供初始化和構建Python項目的工具
• 鎖文件：兩者都生成鎖文件以確保環境可復現

然而，UV的Rust實現使其在速度和資源使用方面具有顯著優勢。此外，UV與現有Python包管理工具的兼容性意味著它可以與其他工具（如pip）一起工作，提供了Poetry更固執己見的方法有時缺乏的靈活性。

4）功能對比表

功能特性	UV	pip+virtualenv	Conda	Poetry
實現語言	Rust	Python	Python	Python
速度	比pip快10-100倍	基準線	慢于pip	快于pip
內存使用	非常高效	較高	高	中等
環境管理	內置	需要單獨工具	內置	內置
依賴解析	快速、現代解析器	基礎	全面	現代解析器
非Python包支持	否	否	是	否
鎖文件	是	否(基本requirements.txt)	是	是
項目結構化	是	否	否	是
包發布	是	是(需要twine)	是	是
兼容性	與現有pip生態系統兼容	標準Python工具	自有生態系統	更固執己見的方法
錯誤處理	清晰的錯誤信息	基本	良好	良好
資源占用	最小	中等	重	中等
科學計算焦點	否	否	是	否
跨平臺一致性	是	有限	優秀	良好

總的來說，UV結合了現有工具的最佳特性，同時通過其Rust實現提供了顯著的性能優勢。對于尋求更快、更可靠的Python包管理解決方案的開發者來說，UV是一個極具吸引力的選擇，特別是對于大型項目或CI/CD環境。

---

2. UV的安裝與常用命令

2.1 安裝UV

UV的安裝非常簡單，支持多種操作系統和安裝方式。以下是幾種常見的安裝方法：

1）使用官方安裝腳本（推薦）

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

2）使用包管理器

# macOS (Homebrew)
brew install uv

安裝完成后，可以通過以下命令驗證安裝是否成功：

uv --version

安裝正確會得到版本號：

uv 0.8.13 (ede75fe62 2025-08-21)

2.2 創建和管理項目

UV提供了一套完整的命令用于創建和管理Python項目：

1）創建新項目

# 創建一個新的Python項目目錄
uv init example
# 運行正確會顯示：Initialized project `example` at `/路徑/example`

有三個默認文件：README.md、main.py、pyproject.toml

查看目錄內容：

cd example
tree -a -L 1
.
├── .git
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

該 main.py 文件包含一個簡單的“Hello world”程序。嘗試一下 uv run main.py：

初始化一個新的虛擬環境： uv venv ，正確運行后得到虛擬環境信息

Using CPython 3.13.1
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

直接運行 main.py 也可以創建虛擬環境

uv run main.py

激活虛擬環境

source .venv/bin/activate

2.3 依賴管理命令

UV 提供了一系列強大的依賴管理命令，以下是最常用的幾個：

1）添加依賴

使用 uv add 命令可以向項目添加依賴。該命令會自動更新 pyproject.toml 文件、鎖文件和項目環境：

# 添加單個包
uv add requests# 指定版本約束
uv add 'requests==2.31.0'# 添加 Git 依賴
uv add git+https://github.com/psf/requests# 從 requirements.txt 文件添加所有依賴
uv add -r requirements.txt -c constraints.txt

2）刪除依賴

使用 uv remove 命令可以刪除項目依賴：

# 刪除包
uv remove requests

3）升級依賴

使用 uv lock 命令配合 --upgrade-package 參數可以升級指定包：

# 升級特定包
uv lock --upgrade-package requests

該命令會嘗試將指定包更新到最新的兼容版本，同時保持鎖文件中其他依賴不變。

4）安裝項目依賴

當你有一個包含 pyproject.toml 的項目時，可以使用以下命令安裝所有依賴：

# 安裝項目依賴
uv pip install -e .# 安裝包含開發依賴
uv pip install -e ".[dev]"

5）同步項目環境

使用 uv sync 命令可以確保項目環境與鎖文件保持同步：

# 同步項目環境
uv sync

6）運行項目命令

uv run 命令可以在項目環境中運行腳本或命令。在每次運行前，UV 會驗證鎖文件是否與 pyproject.toml 同步，并確保環境與鎖文件一致：

# 運行 Python 腳本
uv run main.py

7）構建項目分發包

uv build 命令可用于構建項目的源碼分發包和二進制分發包（wheel）：

# 構建項目
uv build# 查看構建結果
ls dist/
# 輸出示例：
# Successfully built dist/example-0.1.0.tar.gz
# Successfully built dist/example-0.1.0-py3-none-any.whl

這些命令提供了一個完整的項目依賴管理工作流程，從添加依賴、刪除依賴、升級依賴到運行項目和構建分發包。UV 的這些命令設計直觀且高效，大大簡化了 Python 項目的依賴管理。

2.4 使用工具

UV 提供了強大的工具管理功能，可以替代 pipx 等工具來運行和管理 Python 工具。

1）運行工具（不安裝）

uvx 命令可以在不安裝工具的情況下直接運行工具：

# 運行帶參數的工具
uvx pycowsay "Hello from UV"-------------
< Hello from UV >-------------\   ^__^\  (oo)\_______(__)\       )\/\||----w |||     ||

運行 ruff 代碼檢查工具

# 運行 ruff 代碼檢查工具
uvx ruff check .
# All checks passed!uv tool run ruff check .
# All checks passed!

注意：uvx 是 uv tool run 的便捷別名。使用 uvx 運行的工具會在臨時的隔離環境中安裝和運行。

2）指定工具版本

可以使用 @ 語法指定工具的版本：

# 運行特定版本的工具
uvx ruff@0.1.5 check .# 運行最新版本的工具
uvx ruff@latest check .

也可以使用 --from 選項指定更復雜的版本約束：

# 指定版本范圍
uvx --from 'ruff>0.2.0,<0.3.0' ruff check .

3）安裝工具

如果經常使用某個工具，可以將其安裝到持久環境中，并添加到 PATH 中：

# 安裝 ruff 工具
uv tool install ruff# 安裝特定版本的工具
uv tool install 'ruff>=0.3.0'# 從 Git 倉庫安裝工具
uv tool install git+https://github.com/astral-sh/ruff

安裝工具后，可以直接在命令行中運行該工具，無需通過 UV 調用：

# 直接運行已安裝的工具
ruff --version

注意：與 uv pip install 不同，安裝工具不會在當前環境中提供其模塊。這種隔離對于減少工具、腳本和項目之間的依賴沖突非常重要。

4）升級工具

使用 uv tool upgrade 命令可以升級已安裝的工具：

# 升級特定工具
uv tool upgrade ruff# 升級所有工具
uv tool upgrade --all

工具升級會尊重安裝工具時提供的版本約束。例如，如果使用 uv tool install ruff >=0.3,<0.4 安裝了 Ruff，然后運行 uv tool upgrade ruff，則將升級 Ruff 到 >=0.3,<0.4 范圍內的最新版本。

5）使用插件和額外依賴

可以使用 --with 選項添加額外的依賴或插件：

# 運行帶插件的工具
uvx --with mkdocs-material mkdocs serve# 安裝帶插件的工具
uv tool install mkdocs --with mkdocs-material

使用 --from 選項可以運行帶有額外功能的工具：

# 使用額外功能
uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

這些命令使 UV 成為一個強大的 Python 工具管理器，可以替代 pipx 和其他類似工具，并且提供了更高的性能和更多的功能。

3 內部原理

UV 的出色性能不僅僅是因為它使用 Rust 語言開發，更在于其內部實現了多種高效的算法和優化策略。下面我們將揭開 UV 的核心技術原理。

3.1 依賴解析器

UV 使用基于 PubGrub 算法的依賴解析器，這是一種增量版本求解器。與傳統的 SAT 求解器不同，UV 的解析器具有以下特點：

1. 增量解析：從一個部分解決方案開始，逐步選擇包版本，而不是嘗試所有可能的組合。
2. 智能優先級：包的選擇基于優先級系統，URL 包優先級最高，然后是精確版本說明符，再然后是寬松說明符。
3. 版本偏好：優先使用鎖文件和當前環境中的版本，以及最高版本（除非指定其他解析策略）。
4. 預取優化：在后臺預取包的元數據，顯著提高性能。
5. 智能回溯：當檢測到沖突時，解析器會進行回溯，并記錄不兼容項，以避免重復嘗試無效組合。
6. 有意義的錯誤報告：當解析失敗時，提供清晰的錯誤跟蹤，指出沖突的具體包和版本。

3.2 分叉解析

UV 采用了分叉解析器策略，可以處理不同環境下的矛盾需求：

1. 條件依賴：當包有多個帶有不同標記的要求時（如基于 Python 版本或操作系統的條件），解析會被分割。
2. 智能合并：具有相同包的分叉會合并，以保持分叉數量較少。
3. 鎖文件穩定性：鎖文件中會記錄分叉信息，確保解析穩定性。

3.3 Python 版本兼容性

UV 嚴格處理 Python 版本兼容性，確保所有依賴項都能在指定的 Python 版本上正確安裝：

1. 最低版本傳播：如果項目要求 Python >= 3.9，那么聲明了 Python >= 3.10 的包版本會被拒絕。
2. 版本下限尊重：為了簡化和向前兼容，只會尊重 requires-python 中的下限。

3.4 性能優化

UV 的高性能來自于多方面的優化：

1. Rust 實現：使用 Rust 語言開發，具有出色的性能和內存安全性。
2. 并行下載：并行處理包下載和元數據獲取。
3. 智能緩存：全局緩存機制避免重復下載和安裝相同的包。
4. 最小化磁盤操作：優化的文件操作和磁盤訪問模式。
5. 增量處理：在解析和安裝過程中采用增量方法，避免不必要的全量重建。

這些內部原理使 UV 能夠在保持兼容性的同時，實現比傳統工具快 10-100 倍的性能。對于大型項目和復雜依賴關系，這些優化尤為重要。

4 速查表

下面是 UV 工作流程中的常見操作速查表，幫助您快速查找和使用 UV 的各種命令。

4.1 環境管理

操作	UV 命令	傳統對應命令
創建虛擬環境	uv venv	python -m venv .venv
創建指定 Python 版本的虛擬環境	uv venv --python=3.10	python3.10 -m venv .venv
安裝 Python 版本	uv python install 3.10	使用 pyenv 或系統包管理器
列出可用的 Python 版本	uv python list	pyenv versions
激活虛擬環境	使用系統激活方式	source .venv/bin/activate

4.2 包管理

操作	UV 命令	傳統對應命令
安裝單個包	uv pip install requests	pip install requests
從 requirements.txt 安裝	uv pip install -r requirements.txt	pip install -r requirements.txt
安裝當前項目	uv pip install -e .	pip install -e .
安裝開發依賴	uv pip install -e ".[dev]"	pip install -e ".[dev]"
生成鎖文件	uv pip compile requirements.in -o requirements.txt	pip-compile requirements.in -o requirements.txt
升級單個包	uv pip install --upgrade requests	pip install --upgrade requests

4.3 項目管理

操作	UV 命令	傳統對應命令
添加依賴	uv add requests	Poetry: poetry add requests
移除依賴	uv remove requests	Poetry: poetry remove requests
同步環境	uv sync	Poetry: poetry install
升級特定包	uv sync --upgrade-package requests	Poetry: poetry update requests
升級所有包	uv lock --upgrade	Poetry: poetry update
運行腳本	uv run python script.py	Poetry: poetry run python script.py
構建項目	uv build	Poetry: poetry build

4.4 工具管理

操作	UV 命令	傳統對應命令
運行工具(不安裝)	uvx ruff check .	pipx: pipx run ruff check .
運行特定版本工具	uvx ruff@0.1.5 check .	pipx: pipx run --spec=ruff==0.1.5 ruff check .
安裝工具	uv tool install ruff	pipx: pipx install ruff
升級工具	uv tool upgrade ruff	pipx: pipx upgrade ruff
升級所有工具	uv tool upgrade --all	pipx: pipx upgrade-all

整理完畢，完結撒花～🌻

參考地址：

1.UV：下一代Python包管理工具的全面指南，https://www.apframework.com/blog/essay/2025-06-07-Python-UV