uv：新一代 Python 套件管理神器

這篇文章整理自我準備在部門週會上分享的內容。會主動想介紹 uv 其實是被幾個工作中遇到的問題搞到感覺推廣一下也不錯：忘了 activate 結果把套件裝到 global、用 pip 建了太多虛擬環境把公司 OA 的 D 槽塞爆、還有 Ubuntu 24.04 直接禁止用系統 pip 安裝套件等等。

在準備分享的過程中，也意外釐清了一些之前的誤解——例如跨分區其實是用複製而非硬連結，所以省空間的效果會打折扣。同時也學到了一些新東西，像是 uv format、Docker BuildKit 快取、PEP 723 腳本依賴宣告等，這些或許未來工作中都能派上用場。

uv 是由 Astral 公司推出的 Python 工具，也就是開發知名 Linter 工具 Ruff 的團隊。它的目標是成為 Python 生態系中最快、最可靠的套件管理解決方案。

• GitHub 專案位址：astral-sh/uv

核心特性

• 極致的速度：使用 Rust 編寫，快取啟動情境下速度可比 pip 快上 10 到 100 倍
• 先進的快取機制：採用內容定址 (Content-addressed) 技術，加速環境建立且不重複佔用空間
• 全能工具箱：整合了 pip、pip-tools、virtualenv、pyenv、pipx 以及 Poetry 的核心功能

安裝方式

uv 提供多種安裝路徑，建議使用獨立二進位檔安裝，以獲得完整功能：

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

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

透過 pip 安裝 (pip install uv) 不建議，因為該版本不支援 uv self update 一鍵更新功能。

為什麼選擇 uv？

1. 解決系統環境限制 (PEP 668)

在 Ubuntu 24.04 等現代 Linux 系統中，uv 透過自動管理獨立 Python 版本，完美繞過 pip 被阻擋的問題。

2. 高度的向下相容性

內建 uv pip 介面，是傳統 pip 的「掉包替代品」，完全不需改變使用參數。

3. 免手動啟動環境

傳統流程需要 source .venv/bin/activate，而 uv 透過 uv run 直接在環境內執行指令，省去了啟動與切換環境的繁瑣步驟。

4. 全生命週期專案管理

uv 不僅管理依賴，連打包、發佈、甚至格式化程式碼都能一機搞定。

核心功能概覽

專案管理 (取代 Poetry / PDM)

# 初始化新專案
uv init my-project
cd my-project

# 加入依賴並同步
uv add requests
uv sync

💡 uv init 會產生哪些檔案？

• pyproject.toml：核心設定檔，包含專案資訊與依賴。
• .python-version：紀錄專案建議使用的 Python 版本。
• .gitignore：預設排除 .venv 等檔案。
• uv.lock：精確紀錄所有套件版本，確保環境一致性（類似於 poetry.lock 或 - package-lock.json）。

執行程式與自動環境管理

uv run 會確保程式在正確的虛擬環境中執行，若環境尚未建立或依賴有變動，它會自動進行同步。

# 在專案中執行
uv run main.py

如果你只有一個腳本，甚至不需要 uv init。只要在腳本開頭加上 PEP 723 格式的依賴宣告：

# /// script
# dependencies = ["requests"]
# ///
import requests
print(requests.get("https://google.com").status_code)

全域工具管理 (uv tool & uvx)

• 臨時執行 (uvx / uv tool run)：類似 npx，適合只想「用一下就丟」的情境
• 永久安裝 (uv tool install)：將工具安裝在隔離的環境中，並自動加入系統 PATH
  • 例如：uv tool install ruff ，執行：ruff --version
  • 各工具會有各自的獨立環境，不會互相干擾。

鎖定依賴與同步環境

• uv lock：計算專案的依賴關係並更新 uv.lock 檔案
• uv sync：確保 .venv 虛擬環境與 uv.lock 完全同步
  • uv sync 常用參數比較：

    參數	行為	適用情境
    (無參數)	若 lock 檔過期則重新解析，再同步環境	一般開發，開發機上常用
    --locked	驗證 lock 檔與 pyproject.toml 一致才安裝，不一致則報錯	CI 環境，確保沒人忘了更新 lock
    --frozen	跳過驗證，直接依照 lock 檔安裝	Docker build，追求最快速度
    --exclude-newer 2024-12-01T00:00:00Z	只解析該時間點前發佈的版本	重現舊版環境、除錯
    --resolution lowest	解析時選擇最低相容版本	測試套件的最低版本相容性

Python 版本管理

# 查看可用版本
uv python list

# 安裝指定版本
uv python install 3.12

# 鎖定專案版本（建立 .python-version 檔案）
uv python pin 3.11

檢視依賴樹

uv tree

極速代碼格式化

基於 Ruff 的格式化功能，速度比傳統工具快上數十倍：

uv format .

與傳統 Pip 專案的整合

作為 Pip 的替代品

不需要改變專案結構，只需將 pip 改為 uv pip 即可：

uv pip install -r requirements.txt
uv pip list

正式遷移至 uv 架構

# 初始化 uv 專案
uv init

# 匯入現有依賴
uv add -r requirements.txt

# 反向輸出 (相容性)
uv export --format requirements-txt > requirements.txt

uv vs. Poetry

依賴同步更直接

uv sync 會自動偵測虛擬環境中多餘的套件並解安裝，確保開發環境永遠是最簡潔一致的狀態。

解析速度的代差

uv 通常只需幾秒鐘即可完成數百個依賴的解析。

Poetry 仍有優勢之處

• 外掛生態系 (Plugin System)
• 成熟度與發佈流程

Docker 最佳實踐

FROM python:3.12-slim-bookworm
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
COPY pyproject.toml uv.lock ./

# 使用 Docker BuildKit 快取來加速安裝
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

COPY . .
CMD ["uv", "run", "hello.py"]

快取管理

# Windows
$env:UV_CACHE_DIR = "D:\.uv_cache"

# Linux
export UV_CACHE_DIR="/path/to/cache"

效能實測數據

空間佔用對比 (5 個環境)

• 傳統 Pip (Ubuntu): 1.5 GB
• uv (同分區連結): 235 MB（5 個環境僅佔一份空間）

結論

自 2025 年開始，uv 迅速崛起並成為目前 Python 生態系中最炙手可熱的管理工具。它不只是一次效能提升，更是對底層檔案系統特性的極致運用。

從 0.18 秒的安裝神蹟到 Windows 上 27~56 倍的速度飛躍，uv 徹底解決了開發者長久以來的速度與空間焦慮。只要正確設定 UV_CACHE_DIR，這款神器將為你的開發流程帶來跨時代的效率變革。