uv

uv

在 Python 開發環境中，大部分的人接觸可能都是pip install -r requirements.txt 但在 2026 年的現今，主流漸漸往 uv 靠攏，看到更多的可能是執行uv sync來做 virtual environment 同步。

從uv不難看出其當中使用人數不斷增長

為什麼是 uv？

在 uv 出現之前，一個 Python 專案往往需要許多工具來管理、建立虛擬環境，也有可能有人習慣使用 conda 來管理，變成大家環境很難統一。

• pyenv 管 Python 版本
• venv / virtualenv 建虛擬環境
• pip 裝套件
• pip-tools 或 poetry 鎖定依賴版本

每個工具各自有自己的設定檔、快取與行為，有時光是搞懂「我現在該用哪一個」就要花不少時間。除此之外還有幾個長年的痛點：

• 依賴解析慢：在大型專案上 pip install 動輒等上幾分鐘。
• 環境不一致：requirements.txt 只記錄了你裝了什麼，卻不保證隊友裝出來跟你一模一樣。
• 跨平台難重現：同一份依賴在 macOS 與 Linux 上解析結果可能不同。

uv 可以解決的痛點就是：用一個工具取代上面全部。它用 Rust 寫成，主打依賴解析與安裝速度，並用一份 uv.lock 帶有 hash 值確保任何人、任何平台都能還原出一模一樣的環境。

安裝

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# 或用 Homebrew
brew install uv

裝好之後，一個新專案的起手式是這樣：

uv init project      # 建立專案骨架（pyproject.toml）
cd project
uv add requests         # 新增依賴
uv add --dev pytest     # 新增開發用依賴

在這些 uv 操作完之後，如果 terminal 需要吃到環境，也可以使用source .venv/bin/activate來獲取環境

指令對照表

Python 版本管理

當專案裡有 .python-version，uv 會在需要時自動下載對應版本，等於鎖定住了專案 Python 版本。

uv python install 3.13      # 下載指定版本
uv python list              # 列出可用 / 已安裝版本
uv python pin 3.13          # 寫入 .python-version

專案結構與 lockfile

uv 的核心是兩個檔案：

• pyproject.toml — 你手動維護的「意圖」：宣告需要哪些套件、版本範圍、以及相關 formatter/linter 規定
• uv.lock — uv 自動產生的「事實」：把整個依賴樹鎖定到確切版本與雜湊值。

依賴群組則可以把 dev、測試、文件等依賴分開，避免正式環境上多安裝了不必要的套件。

uv add --dev pytest ruff types-boto3
uv sync --no-dev        # 部署時只裝正式依賴

進階用法

用 uvx 取代 pipx

uvx ruff check .             # 不需要事先安裝 ruff
curl -s https://example.com | uvx python -m json.tool  # 不用限制在有 uv 專案環境中執行

從既有專案遷移

• requirements.txt → uv add -r requirements.txt，再把產生的 pyproject.toml 與 uv.lock取代掉requirements.txt

總結

轉換到uv生態系之後，在專案架構上像是拿一把瑞士刀，過往可能要用蠻多套來管理，現在一套uv可以完成許多操作。 uv tree以及uv add --upgrade pkg算是我很喜歡的功能，可以清晰的看出依賴並且做版本升級，不會安裝到一半才要撞到版本依賴等問題，然後又要回滾。

另外一個就是壓版號，uv version可以快速看到當前專案版號，然後也可以uv version --bump major|minor|patch來輕鬆管理。