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

# 升級特定套件到符合規範的最新版
uv lock --upgrade-package requests

# 升級所有套件
uv lock --upgrade

檢查套件狀態

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

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

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

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

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

1. 全域快取 (Global Cache)

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

在建立專案的虛擬環境時，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.lock 是完全同步的。

uv run main.py

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

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

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