Python 高效開發利器 uv 全指南：取代 pip/pipenv/poetry/pyenv 的極速解決方案

🎯 重點摘要： uv 是由 Astral 開發的極速 Python 工具，
  ① 10-100x 快：使用 Rust 重寫，取代 pip、pipenv、poetry、pyenv、pipx 全部：建環境比以前快好幾十倍
  ② 一個工具通通包：初始化專案、管理套件、建立虛擬環境、切換 Python 版本、執行工具、發布包、管理工作區 (monorepo) 通通在一個指令裡
  ③ 現代專案結構：pyproject.toml + uv.lock 取代 requirements.txt，universal lockfile 保證跨平台一致
  ④ 無痛遷移：uv pip install 幾乎 100% 兼容 pip 介面，舊專案不用改一個字就能加速
  ⑤ 腳本即執行：Python 腳本支援行內宣告 dependencies，直接執行不用手動安裝 — 像是 Node.js 的 npx 但更強

Python 開發現狀：為什麼需要 uv？

我想大家肯定都遇到過這種狀況：

• 需要切 Python 版本 → pyenv install 3.12 等個幾分鐘
• 建虛擬環境 → python -m venv .venv 又跑不動，明明裝過的套件呢
• 裝套件 → pip install -r requirements.txt 又花個 5 分鐘以上
• 遷移到新電腦 → 套件不見一半，requirements.txt 也不知道鎖幾個版本
• 想用 ruff 或 black 這種 CLI 工具 → pipx install，又是一套流程

uv 就是要解決這一切。 它是用 Rust 寫的 Python 工具，能夠同時取代 pip、pipenv、poetry、pyenv、pipx、virtualenv 這些零零散散的工具。效能上，uv 比 pip 快 10 到 100 倍，連 dependency resolver 也在 0.1 秒開內完成。

更重要的是，它整合完觀整個 Python 開發流程：初始化專案 → 建立虛擬環境 → 管理套件 → 切換 Python 版本 → 執行指令 → 發布包，全部一個工具搞定。告別那個「環境有問題」的痛。

安裝

uv 支援 macOS、Linux 和 Windows，且不需要預先安裝 Python 或 Rust。選擇一個你喜歡的方式來安裝：

推薦：使用官方安裝腳本

# 安裝到 ~/.local/bin/
curl -LsSf https://astral.sh/uv/install.sh | sh

安裝完成後，把 ~/.local/bin 加到你的 PATH 裡（如果安裝腳本沒有自動新增）：

# bash / zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# 或
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

其他安裝方式

驗證安裝

$ uv --version
uv 0.12.5

5 分鐘上手：建立你的第一個 uv 專案

跟 Docker 一樣，uv 也會幫你 scaffold 一個完整的專案結構：

$ uv init my-project
Initialized project `my-project` at `/Users/robert/my-project`

$ cd my-project

這會建立：

my-project/
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
└── src/
    └── my_project/
        └── __init__.py

新增一個套件

$ uv add requests
Resolved 15 packages in 12ms
Prepared 15 packages in 38ms
Installed 15 packages in 2ms
 + requests==2.32.3
 + charset-normalizer==3.3.0
 + ...

$ uv add ruff --dev
# --dev 把它放到開發者依賴組
Resolved 12 packages in 8ms

順便幫你建好虛擬環境 .venv 並生成 uv.lock。整個過程比 pip 加倍快。

執行程式碼

$ echo 'import requests; print(requests.__version__)' | uv run python
2.32.3

uv run 會自動確保虛擬環境是最新的（跟 lockfile 同步），然後執行指令。

核心概念：pyproject.toml 取代 requirements.txt

uv 使用現代的 pyproject.toml 格式來宣告專案資訊和依賴。不用再維護 requirements.txt 加 requirements-dev.txt 這套古早組合。

基本格式

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
  "requests>=2.31",
  "pydantic>=2.0",
]

[project.optional-dependencies]
dev = [
  "ruff>=0.5.0",
  "pytest>=8.0",
]

[build-system]
requires = ["uv_build>=0.12.6,<0.13"]
build-backend = "uv_build"

dependency-groups：取代 extras_require 的現代寫法

uv 支援 PEP 735 的 dependency-groups，也就是傳統的「extras」進化版：

[dependency-groups]
dev = ["ruff", "pytest"]
test = ["pytest", "pytest-cov"]
docs = ["mkdocs-material", "mkdocstrings[python]"]

然後你可以用 uv sync --group dev --group test 安裝指定組，或者uv sync --all-groups 裝全部。

💡 Pro 小技巧： uv add --group lint ruff 等同於把 ruff 加到 [dependency-groups] lint 裡，比傳統的 pip install -e .[dev] 更直觀。

Python 版本管理：不用 pyenv 了

uv 內建 Python 版本下載和管理，跟 pyenv 功能一樣：

自動下載 Python

# 下載並使用最新的穩定版 Python
$ uv python install
Installed Python 3.13.1 in 1.2s

# 指定版本
$ uv python install 3.12 3.11 3.10
Installed Python 3.12.6 in 0.8s
Installed Python 3.11.9 in 0.7s
Installed Python 3.10.15 in 0.9s

專案需求：.python-version 檔案

uv 會自動讀取 `.python-version` 檔案 (或 pyproject.toml 中的 requires-python) 來決定要用哪個 Python 版本：

# .python-version
3.13.1

當你 cd 到有這個檔案的目錄，uv 會自動啟用對應版本，跟 pyenv 運作一樣。但不需要 pyenv 這層中介 — uv 直接下載對應的 Python 來用。

一次性指定版本執行

# 用 3.10 執行一個檔案
$ uv run --python 3.10 my_script.py

# 或指定到 uvx（稍後介紹）
$ uvx python@3.12 -c "print('hello')"

uvx：不用安裝就能執行的工具

這部分對應的是 pipx 的功能，但更強更快。uvx 會在臨時的環境下下載並執行一個 CLI 工具，用完就丟，不污染你的系統。

基本用法

# 執行最新版的 ruff（不用先 pipx install ruff）
$ uvx ruff check .

# 指定版本
$ uvx ruff@0.6.0 check .

# 清除暫存的工具快取
$ uvx --clean

常見 uvx 應用

• uvx httpie — 現代 curl 替代
• uvx black — 快速格式化 Python
• uvx ipython — 進階 REPL
• uvx yt-dlp — YouTube 下載工具
• uvx http-server — 快速本地 HTTP 伺服器

持續安裝工具（如 pipx install）

如果你真的要長期安裝一個 CLI 工具，就用 uv tool install：

$ uv tool install ruff
Installed ruff@0.6.0 to ~/.local/bin/

$ which ruff
/Users/robert/.local/bin/ruff

✅ 快速對比：pipx install ruff 會花 ~2-3 秒，而 uv tool install 通常 < 1 秒，因為 uv 直接從 prebuilt wheels 快取來安裝。

uv run：取代 python 執行的智慧指令

uv run 是 uv 的「智慧執行器」，它會：

1. 自動建立/更新 .venv
2. 確保所有 dependencies 都是 lockfile 的版本
3. 在同步好的環境下執行指令

# 執行 python 指令
$ uv run python hello.py

# 執行測試
$ uv run pytest tests/

# 執行一個在 pyproject.toml 裡的 script entry point
$ uv run my-project  # 等於執行 [project.scripts] 裡的 my-project

# 執行一個一次性套件（不會被加入依賴）
$ uv run --with requests python -c "import requests; print(requests.__version__)"

# 在「乾淨」環境執行（不使用 .venv）
$ uv run --isolated --no-project --with httpx python -c "import httpx; print(httpx.__version__)"

管理專案依賴的完整指令

⚠️ CI/CD 一把標配：在 CI 裡，用 uv sync --locked 來確保「本地 lockfile 和 CI 同步」。如果 lockfile 有改動但沒提交，uv 會直接報錯告訴你「快提交 lockfile 啦」。

行內腳本：Python pip 的 npx

uv 支援在 Python 腳本的頭部加上 # /// 區塊來宣告 dependencies，執行時 uv 會自動建立臨時環境並安裝：

#!/usr/bin/env -S uv run --script
# ///
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///

import httpx

response = httpx.get("https://example.com")
print(response.status_code)

然後直接執行：

$ chmod +x script.py
$ ./script.py

uv 會自動下載 Python 3.12+，建一個臨時環境，安裝 httpx，然後執行腳本。這樣的腳本帶環境依賴，別人執行就不用問「要裝什麼」。

初始化腳本模板

$ uv init --script my_tool.py --python 3.13
# or
$ uv init -S my_tool.py  # --script 的短版

Workspaces：monorepo 也輕鬆搞

對於多 package 專案（monorepo），uv 提供 Cargo 風格的 workspaces 功能：

my-org/
├── pyproject.toml          # workspace root
├── packages/
│   ├── api/
│   │   └── pyproject.toml  # member
│   └── cli/
│       └── pyproject.toml  # member
└── uv.lock

根專案設定

# pyproject.toml (root)
[project]
name = "my-org"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = []

[tool.uv.workspace]
members = ["packages/*"]

成員專案

# packages/api/pyproject.toml
[project]
name = "api"
version = "0.1.0"
dependencies = ["requests"]

[tool.uv.sources]
cli = { workspace = true }  # 從 workspace 引用其他 member

💡 實戰應用：workspace root 的 lockfile 會管理 所有 member 的 dependencies，確保整個 monorepo 的依賴是一致且可重現的。非常適合公司專案或函式庫套件集合。

發布包裝：build + publish

uv 也內建打包和發布功能，取代 setup.py + twine 的組合：

建立發佈檔案

$ uv build
Building my-project...
Created dist/
  my_project-0.1.0-py3-none-any.whl  (12.3KB)
  my_project-0.1.0.tar.gz          (12.1KB)

發布到 PyPI

$ uv publish
Publishing my_project to PyPI...
Login successful!  # 使用 PyPI Token
Uploading my_project-0.1.0-py3-none-any.whl  (1.2KB) ━━━━━━━━━━ 100%
Uploading my_project-0.1.0.tar.gz  (1.1KB) ━━━━━━━━━━ 100%

支援 `--username`/`--password` 或環境變數 `UV_PUBLISH_TOKEN`；也支援發布到私有 registry：uv publish --index-url https://your-pypi.example.com/。

遷移指南：從 pip/pipenv/poetry 無痛搬家

最好的地方：uv pip 系列指令幾乎 100% 兼容 pip 界面，所以你可以直接用 uv 取代 pip，慢慢遷移。

從 pip 遷移（零改動）

從 requirements.txt 升級到 pyproject.toml

$ uv init
# 然後把舊 requirements.txt 的內容加過來
$ uv add -r requirements.txt
# 或保持版本鎖定
$ uv add -r requirements.in -c requirements.txt

從 poetry/poetry 遷移

# 先把現有的 pyproject.toml 的 dependency groups 轉成 dependency-groups
# （uv 會自動處理大部分格式）

$ uv sync        # 等於 poetry install
$ uv add    # 等於 poetry add 
$ uv lock        # 等於 poetry lock
$ uv run    # 等於 poetry run 

快取機制：為什麼 uv 這麼快

uv 有一個全域快取區（預設在 ~/.cache/uv/ 或 uv cache dir 顯示的路徑），所有虛擬環境和下載的 wheels 會被快取起來：

$ uv cache dir
/Users/robert/.cache/uv

$ uv cache clean   # 清空快取
$ uv cache prune   # 清除無用項目

# 在 CI 裡快取
# GitHub Actions
- uses: actions/cache@v4
  with:
    path: ~/.cache/uv
    key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}

🚀 硬連結加速：uv 在 Linux/macOS 使用 hard links，同一套件安裝到幾十個虛擬環境幾乎不用額外磁碟空間。加上 resolver 使用並查集（union-find）演算法，解析 dependencies 的速度比 pip 快好幾個數量級。

常見指令速查表

常見問題 FAQ

uv 和 poetry 選哪個？

如果你現在用 poetry，uv 基本上可以無縫取代：指令差不多、效能快上好幾倍、還多了 Python 版本管理和 uvx 工具執行功能。遷移成本很低，風險也小。建議在新專案直接用 uv，舊專案視情況遷移。

uv 是否支援 Windows？

完全支援，並且 Windows 上的效能也很好。uv 的 Rust 內核天生跨平台。

可以在 CI/CD 裡面用 uv 嗎？

可以，GitHub Actions 有官方 action astral-sh/setup-uv，內建快取支援：

steps:
  - uses: actions/checkout@v4
  - uses: astral-sh/setup-uv@v9
    with:
      enable-cache: true
      cache-dependency-glob: "uv.lock"
  - run: uv sync --locked
  - run: uv run pytest

uv.lock 會污染 git diff 嗎？

uv.lock 的格式非常穩定，diff 非常小。通常只有新增/移除的套件會產生少量 diff，日常 uv sync 不會動到 lockfile。如果你只是加了一個 dev 工具，lockfile 的改變通常就 1-2 行。

有沒有像 conda 的環境隔離功能？

uv 本身不支援 conda 的多環境管理語意，但 uv 的 workspaces + virtual environment 已經足以應付大多數場景。需要系統級套件（如 GDAL）時，建議在系統層面使用 conda/apt，然後再用 uv 管理 Python 依賴。

最佳實務

1. commit uv.lock： lockfile 保證團隊都裝到一模ㄧ樣的版本，一定要放進版本控制。
2. CI 用 --locked 旗標：uv sync --locked 在 CI 裡可避免「lockfile 跑版」的問題。
3. .gitignore 記得加 .venv：uv 會在初始化時幫你加，但自動建的 .gitignore 確實會排除 .venv。
4. 開發依賴放 dependency-groups：不要全部塞 [project.dependencies]，lint/test/docs 各放一組。
5. 快取要設定在 CI：如果不用 setup-uv action，手動設定 UV_CACHE_DIR 環境變數來快取。

小結

uv 真正的價值在於 簡化 Python 開發的工具鏈 —— 一個指令就搞定了過去需要 pip + venv + pyenv + pipx + poetry 這五套工具才能完成的事。

效能上，uv 比 pip 快 10-100 倍，並且 universal lockfile 保證了跨平台的一致性。結合 pyproject.toml + dependency-groups，整個專案的依賴管理變得現代化又可預測。

最近在開新專案的話，強烈推薦直接跳上 uv。舊專案也可以 uv pip install 漸進式遷移，風險幾乎為零。

🎯 5 分鐘上手： pip install uv → uv init → uv add requests → uv run python -c "import requests; print(requests.__version__)"。就這樣，你已經擁有一個速度驚人的 Python 開發環境了！