Python uv 極速套件管理工具

uv 是由 Astral（Ruff 的開發團隊）推出的 Python 套件安裝與專案管理工具。它的最大特色就是極致的速度。它是用 Rust 編寫的，旨在取代 pip, pip-tools 甚至 poetry。

為什麼選擇 uv？

1. 速度快：通常比 pip 快 10-100 倍。
2. 相容性：設計為 pip 的直接替代品 (drop-in replacement)。
3. 整合性：單一工具整合了解析 (compile)、同步 (sync)、安裝 (install) 和虛擬環境管理。
4. Rust 核心：利用 Rust 的效能優勢進行平行下載和解析。

觀念釐清：uv pip ... vs uv ... 專案模式

初學者常會困惑：為什麼安裝套件有 uv pip install 也有 uv add？這是因為 uv 同時支援兩種不同的工作模式：

1. Pip 相容模式 (uv pip)

這是為了讓習慣傳統 pip 的開發者能平滑轉移。

• 用途：如果你只是想快速在環境中裝個套件，或者正在維護沒有 pyproject.toml 的舊專案。
• 特色：它直接操作虛擬環境，不會幫你更新專案配置文件。

2. 現代專案模式 (uv)

這是 uv 官方最推薦、也是最能發揮其威力的模式。

• 用途：開發新專案、需要環境 100% 可重現（Reproducible）時。
• 特色：使用 uv add 時，它會自動確保 pyproject.toml 與 uv.lock 同步更新。這確保了你、同事與伺服器上的環境永遠一致。

一句話總結：

如果你是開發一個完整的專案，請永遠優先選用專案模式（uv add）；如果你只是在做臨時性的腳本測試或維護舊專案，才使用 uv pip。

安裝

Mac / Linux:

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

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

基礎指令與 Pip 替代模式

uv 可以完美替代傳統的 pip 工作流，但在速度上有了質的飛躍。

建立虛擬環境：uv venv

# 建立預設的 .venv
uv venv

# 指定 Python 版本建立
uv venv --python 3.11

安裝與移除套件：uv pip

# 安裝套件
uv pip install requests

# 移除套件 (僅限 pip 模式)
uv pip uninstall requests

# 產生鎖定檔案 (類似 pip-compile)
uv pip compile requirements.in -o requirements.txt

# 同步環境 (將環境調整到與 requirements.txt 完全一致)
uv pip sync requirements.txt

現代化專案管理 (Project Workflow)

uv 支援現代化的專案工作流，這也是目前官方最推薦的使用方式，它會自動管理 pyproject.toml 與 uv.lock。

初始化專案：uv init

uv init my-project
cd my-project

管理套件：add, remove, upgrade

在專案模式下，uv 會確保你的環境始終處於「鎖定」狀態。

# 新增套件 (會自動更新 pyproject.toml 與 uv.lock)
uv add requests

# 移除套件 (會自動從配置與環境中移除)
uv remove requests

# 更新 Lock 檔，升級特定套件 (需執行 uv sync 才會真正安裝)
uv lock --upgrade-package requests

# 更新 Lock 檔，升級所有套件
uv lock --upgrade

# 執行同步，將更新後的 Lock 檔套用到目前環境
# 實際更新
uv sync

upgrade 套件分成兩個步驟，一個是更新 Lock 檔，一個是同步環境，這主要是為了確保團隊開發的一致性。如果你覺得分兩次跑很麻煩，可以直接使用這個指令，它會同時更新 Lock 檔並同步環境：

uv sync --upgrade

匯出依賴：uv export

雖然 uv 使用 uv.lock，但有時為了部署到不支援 uv 的環境（如某些 Docker image 或舊式 PaaS），你需要 requirements.txt。

# 將 uv.lock 轉換為 requirements.txt
uv export --format requirements-txt > requirements.txt

檢查套件狀態

# 列出目前環境安裝的套件 (條列式)
uv pip list

# 檢查哪些套件已經過時了 (有新版本可用)
uv pip list --outdated

# 顯示視覺化的依賴樹 (非常推薦，看誰依賴誰)
uv tree

全域工具管理：uv tool

uv 也可以取代 pipx 來管理全域的 Python CLI 工具（例如 black, ruff, httpie）。

# 安裝工具 (可在系統任何地方使用)
uv tool install ruff

# 執行工具 (不需安裝，暫時下載執行)
uvx ruff check .
# 或者
uv tool run ruff check .

# 列出已安裝的工具
uv tool list

深度解析：虛擬環境運作機制

為什麼 uv 這麼快？除了 Rust 本身的效能，它的虛擬環境管理技術也與眾不同。

1. 全域快取 (Global Cache)

當你安裝一個套件（例如 pandas）時，uv 會先將它下載到電腦的全域快取目錄中。

2. 硬連結 (Hard Link) 技術

在建立專案的虛擬環境時，uv 不會真的「複製」套件檔案，而是建立一個硬連結指向全域快取。

• 優點 1：安裝幾乎是瞬間完成（只是建立連結）。
• 優點 2：節省大量硬碟空間。如果你有 10 個專案都用 pandas，它在硬碟中實際上只佔用一份空間。

Python 版本管理與切換

這可能是 uv 最強大的功能之一：它甚至能幫你管理電腦上的 Python 編譯版本。

下載 Python 版本

你不再需要 pyenv，uv 可以直接幫你安裝各個版本的 Python。

# 列出可用的版本
uv python list

# 安裝特定版本
uv python install 3.12

固定專案版本：uv python pin

如果你希望某個專案強制使用特定的 Python 版本，可以使用 pin 指令。

uv python pin 3.10

這會在目錄下建立一個 .python-version 檔案。之後在該目錄執行 uv run 或 uv sync 時，uv 就會自動選用該版本的 Python。

執行腳本與臨時環境：uv run

uv run 不僅僅是執行腳本，它還能建立臨時的環境。

# 執行專案內的腳本 (自動同步環境)
uv run main.py

# 執行帶有臨時依賴的腳本 (不需安裝到專案中)
uv run --with requests script.py

# 執行任意命令
uv run python -c "import requests; print(requests.__version__)"

此外，uv 支援 PEP 723 內聯腳本元數據。你可以在 Python 檔案開頭宣告依賴：

# script.py
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests",
# ]
# ///

import requests
print(requests.get("https://httpbin.org/get").status_code)

直接執行 uv run script.py，uv 會自動準備好該腳本所需的隔離環境並執行。

總結：uv 核心優勢實戰清單

• 專案管理：使用 uv init, uv add, uv remove 取代手動編輯 requirements。
• 極速安裝：利用 uv.lock 與全域快取實現重複安裝秒完成。
• 版本無憂：透過 uv python 指令與 .python-version 檔案解決版本衝突。

uv 不僅是一個工具，更是一套更乾淨、更現代的 Python 開發標準。