📚 延伸閱讀

這篇文章要解決什麼問題？

新人：「我要裝 Python 套件，pip、poetry、pipenv、conda 到底用哪個？」

資深工程師：「現在有個新工具叫 uv，一個就能取代它們全部。」

新人：「又一個新工具？學不完了…」

資深工程師：「這個真的值得學，安裝套件快 10-100 倍，而且指令很簡單。」

新人：「真的有那麼快？」

資深工程師：「用 Rust 寫的，我們專案從 poetry 換過來後，CI 時間少了一半。」

這篇文章會讓你學會：

  • uv 解決什麼問題
  • 安裝與基本設定
  • 專案管理（init、add、sync）
  • 執行程式（run）
  • Python 版本管理

技術概念

uv 是什麼？

uv 是 Astral 公司用 Rust 開發的 Python 套件與專案管理工具，可以取代：

傳統工具 功能 uv 對應指令
pip 安裝套件 uv add / uv pip install
pip-tools 鎖定依賴 uv lock
poetry 專案管理 uv init / uv add
pyenv Python 版本管理 uv python install
virtualenv 虛擬環境 uv venv
pipx 全域工具 uv tool install

為什麼選 uv？

比較項目 pip poetry uv
安裝速度 慢 中等 極快（10-100x）
依賴解析 基本 完整 完整
Lock 檔 無 有 有
虛擬環境 需另裝 內建 內建
Python 版本管理 無 無 內建
學習曲線 低 中 低

速度比較

安裝 Django + 相依套件：

pip:     23.4 秒
poetry:  12.1 秒
uv:       0.8 秒  ← 快 29 倍

這個速度差異在 CI/CD 環境中特別明顯，可以大幅縮短建置時間。

安裝 uv

Linux / macOS / WSL

# 官方安裝腳本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 重新載入 shell 設定
source ~/.bashrc   # 或 source ~/.zshrc

# 驗證安裝
uv --version    # uv 0.8.4

其他安裝方式

# Homebrew (macOS)
brew install uv

# pipx（如果已有 Python 環境）
pipx install uv

# pip（不建議，可能有權限問題）
pip install uv

自動補全（選用）

# Bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

# Fish
uv generate-shell-completion fish > ~/.config/fish/completions/uv.fish

跟著做：專案管理

1. 初始化專案

# 建立新專案目錄
mkdir my-project && cd my-project

# 初始化 uv 專案
uv init

執行後會產生：

my-project/
├── .python-version    # Python 版本
├── pyproject.toml     # 專案設定
├── README.md          # 說明文件
└── hello.py           # 範例程式

2. 新增套件

# 新增套件
uv add fastapi

# 新增多個套件
uv add fastapi uvicorn sqlalchemy

# 新增開發用套件（不會打包到正式環境）
uv add --dev pytest ruff

# 指定版本
uv add "requests>=2.28,<3.0"

執行後：

  • pyproject.toml 會更新 dependencies
  • uv.lock 會鎖定所有相依套件的版本
  • .venv/ 虛擬環境會自動建立並安裝套件

3. 移除套件

uv remove requests

4. 同步依賴

當你 clone 一個專案，或 uv.lock 有更新時：

# 根據 uv.lock 安裝所有套件
uv sync

# 包含開發套件
uv sync --dev

5. 更新套件

# 更新所有套件
uv lock --upgrade

# 更新特定套件
uv lock --upgrade-package requests

跟著做：執行程式

uv run 基本用法

uv run 會自動在虛擬環境中執行指令，不需要手動 activate：

# 執行 Python 檔案
uv run python main.py

# 執行模組
uv run python -m pytest

# 執行套件提供的指令
uv run uvicorn main:app --reload

# 執行測試
uv run pytest tests/ -v

# 執行 linter
uv run ruff check .

對比傳統方式

# 傳統方式（需要手動管理虛擬環境）
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py
deactivate

# uv 方式（一行搞定）
uv run python main.py

常見開發指令

# 啟動 FastAPI 開發伺服器
uv run uvicorn main:app --reload --port 8000

# 執行資料庫遷移
uv run alembic upgrade head

# 執行測試並顯示覆蓋率
uv run pytest --cov=app tests/

# 格式化程式碼
uv run ruff format .

# 檢查程式碼風格
uv run ruff check .

跟著做：Python 版本管理

uv 內建 Python 版本管理，不需要另外安裝 pyenv。

安裝 Python

# 安裝最新穩定版
uv python install

# 安裝指定版本
uv python install 3.12

# 安裝多個版本
uv python install 3.11 3.12

查看已安裝版本

uv python list

輸出範例：

cpython-3.12.3-linux-x86_64-gnu    /home/ct/.local/share/uv/python/cpython-3.12.3
cpython-3.11.9-linux-x86_64-gnu    /home/ct/.local/share/uv/python/cpython-3.11.9

固定專案 Python 版本

# 設定專案使用 Python 3.12
uv python pin 3.12

這會建立或更新 .python-version 檔案，團隊成員都會使用相同版本。

使用特定版本執行

# 用 Python 3.11 執行
uv run --python 3.11 python main.py

pyproject.toml 設定

uv 使用標準的 pyproject.toml 格式：

[project]
name = "my-project"
version = "0.1.0"
description = "我的專案"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.109.0",
    "uvicorn>=0.27.0",
    "sqlalchemy>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.2.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=8.0.0",
    "ruff>=0.2.0",
]

常用設定

欄位 說明
requires-python Python 版本需求
dependencies 正式環境依賴
[project.optional-dependencies] 選用依賴群組
[tool.uv] uv 專屬設定

進階功能

1. 從 requirements.txt 遷移

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

# 匯入開發依賴
uv add --dev -r requirements-dev.txt

2. 匯出 requirements.txt

如果需要相容舊系統：

# 匯出所有依賴
uv pip compile pyproject.toml -o requirements.txt

# 匯出含開發依賴
uv pip compile pyproject.toml --extra dev -o requirements-dev.txt

3. 全域工具安裝

# 安裝全域工具（類似 pipx）
uv tool install ruff
uv tool install black

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

# 執行全域工具
uvx ruff check .

4. 快取管理

# 查看快取位置
uv cache dir

# 清除快取
uv cache clean

常用指令速查

專案管理

指令 說明
uv init 初始化新專案
uv add <套件> 新增套件
uv add --dev <套件> 新增開發套件
uv remove <套件> 移除套件
uv sync 同步依賴
uv lock 更新 lock 檔
uv lock --upgrade 更新所有套件

執行程式

指令 說明
uv run python <檔案> 執行 Python 檔案
uv run <指令> 在虛擬環境中執行指令
uv run --python 3.11 <指令> 指定 Python 版本執行

Python 版本

指令 說明
uv python install 安裝 Python
uv python install 3.12 安裝指定版本
uv python list 列出已安裝版本
uv python pin 3.12 固定專案版本

其他

指令 說明
uv --version 查看版本
uv self update 更新 uv
uv cache clean 清除快取

常見問題

1. 找不到 Python

# 解法：用 uv 安裝 Python
uv python install 3.12

2. 虛擬環境在哪裡？

uv 預設建立在專案目錄的 .venv/：

ls -la .venv/

3. 如何手動啟用虛擬環境？

通常不需要，uv run 會自動處理。但如果需要：

source .venv/bin/activate

4. 與 IDE 整合

大多數 IDE（VS Code、PyCharm）會自動偵測 .venv/，如果沒有：

  • VS Code：Ctrl+Shift+P → “Python: Select Interpreter” → 選擇 .venv/bin/python
  • PyCharm：Settings → Project → Python Interpreter → 選擇 .venv/bin/python

5. CI/CD 使用

# GitHub Actions 範例
- name: Install uv
  uses: astral-sh/setup-uv@v4

- name: Install dependencies
  run: uv sync

- name: Run tests
  run: uv run pytest

小結

概念 重點
uv 用途 取代 pip、poetry、pyenv 的一站式工具
安裝 curl -LsSf https://astral.sh/uv/install.sh \| sh
專案管理 uv init、uv add、uv sync
執行程式 uv run 自動處理虛擬環境
Python 版本 uv python install/list/pin
優勢 快 10-100 倍、指令簡單、功能完整

現在你可以用 uv 來管理 Python 專案了！

參考資源