超快速 Python 套件管理：uv 完全教學

一. 前言

#

你有沒有遇過這種情況：

• pip install 一個大套件（比如 torch 或 pandas）要等好幾分鐘？
• 建虛擬環境、管理 Python 版本，需要同時裝 venv、pyenv、pip-tools、pipenv⋯⋯工具越來越多，頭越來越痛？
• 每次開新專案都在搞環境搞半天，程式碼還沒寫就先花了一個小時？
• 團隊成員的環境不一致，「在我的電腦上可以跑」變成日常？

如果你中了以上任何一項，那你一定要認識 uv！

uv 是由 Astral（就是做超快 Python linter ruff 的那家公司）用 Rust 打造的次世代 Python 套件管理工具。有多快？官方數據是比 pip 快 10 到 100 倍。拍拍君親測，真的快到懷疑人生 🚀

更重要的是，uv 把以前需要好幾個工具才能做到的事情，全部整合在一起：

一個工具搞定所有事情！

二. 安裝 uv

#

macOS / Linux

#

最簡單的方式：

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

或用 Homebrew（拍拍君推薦，方便更新）：

brew install uv

Windows

#

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

或用 winget：

winget install --id=astral-sh.uv

確認安裝

#

uv --version
# uv 0.10.x

如果你看到版本號，恭喜，你已經準備好起飛了！

三. 用 uv 管理 Python 版本

#

以前要用 pyenv 才能管理多個 Python 版本，裝完 pyenv 還要設一堆 shell 設定，有時候編譯 Python 還會缺 header⋯⋯現在 uv 直接搞定，而且是下載預編譯好的版本，不用等編譯！

列出可用版本

#

uv python list

這會列出所有可安裝的 Python 版本，包括 CPython 和 PyPy。

安裝特定版本

#

# 安裝 Python 3.12
uv python install 3.12

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

# 安裝特定小版本
uv python install 3.12.8

固定專案版本

#

# 在專案中固定 Python 版本
uv python pin 3.12

這會在專案目錄建立 .python-version 檔案，確保團隊都用同一個版本。

查看已安裝版本

#

uv python list --only-installed

是不是比 pyenv 簡單多了？不需要 pyenv init、不需要改 .bashrc、不需要 pyenv global/local。

四. 建立專案與虛擬環境

#

從零開始建新專案

#

# 建立新專案（自動建立 pyproject.toml + .venv）
uv init my-awesome-project
cd my-awesome-project

uv 會自動幫你建立一整套完整的專案結構：

my-awesome-project/
├── .python-version    # Python 版本
├── .venv/             # 虛擬環境
├── README.md          # 說明文件
├── pyproject.toml     # 專案設定（取代 setup.py + requirements.txt）
└── hello.py           # 範例程式

打開 pyproject.toml，你會看到：

[project]
name = "my-awesome-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

乾淨、標準、現代。

對現有專案加入 uv 管理

#

如果你有一個已經存在的專案：

cd existing-project

# 建立虛擬環境
uv venv

# 指定 Python 版本
uv venv --python 3.12

# 如果有 requirements.txt，直接匯入
uv add -r requirements.txt

手動啟動虛擬環境

#

大部分時候你不需要手動啟動虛擬環境（uv run 會自動使用），但如果你想的話：

source .venv/bin/activate    # macOS / Linux
.venv\Scripts\activate       # Windows

五. 套件管理：uv 最讓人驚豔的地方

#

安裝套件

#

# 加入依賴（自動更新 pyproject.toml + uv.lock）
uv add requests

# 一次加入多個
uv add pandas numpy matplotlib

# 加入開發用依賴（不會被打包進正式版）
uv add --dev pytest ruff mypy

# 指定版本範圍
uv add "fastapi>=0.100"
uv add "pydantic~=2.0"

每次 uv add 都會自動：

1. 解析依賴關係（超快！）
2. 更新 pyproject.toml
3. 更新 uv.lock（鎖定精確版本）
4. 安裝到虛擬環境

移除套件

#

uv remove requests

乾淨移除，連帶更新 lock 檔。

同步環境

#

當你從 Git 拉下來一個用 uv 管理的專案：

# 根據 uv.lock 安裝所有依賴（精確版本）
uv sync

# 只安裝正式依賴（不含 dev）
uv sync --no-dev

查看依賴樹

#

uv tree

這會顯示清晰的依賴關係樹狀圖，很容易找到衝突或不需要的間接依賴。

六. uv run：最常用的指令

#

uv run 是拍拍君最喜歡的功能 —— 自動在虛擬環境中執行程式，不用手動 activate！

# 執行 Python 腳本
uv run python hello.py

# 執行 pytest
uv run pytest

# 執行 ruff 檢查
uv run ruff check .

# 甚至可以直接跑模組
uv run python -m http.server 8000

uv run 會自動：

1. 檢查虛擬環境是否存在（沒有就建一個）
2. 檢查依賴是否同步（不同步就自動 uv sync）
3. 在虛擬環境中執行指令

你永遠不用再手動 source .venv/bin/activate！

七. uvx：一次性工具執行

#

有時候你只想跑一次某個工具，不想裝到專案裡。uvx 就是為這個場景設計的，就像 Node.js 的 npx：

# 臨時使用 black 格式化（不用安裝到專案）
uvx black my_script.py

# 臨時跑 jupyter notebook
uvx jupyter notebook

# 用 cookiecutter 建立專案模板
uvx cookiecutter gh:audreyfeldroy/cookiecutter-pypackage

# 執行特定版本的工具
uvx --python 3.12 ruff check .

用完就丟，不會污染你的環境！

八. 速度實測

#

這是拍拍君在 M4 Mac 上的實測結果（冷快取）：

📌 以上數據為概估，實際速度依網路與系統而異。重點是量級差距 —— uv 不是快一點點，是快一個數量級！

為什麼這麼快？因為 uv 是用 Rust 寫的，而且：

• 並行下載套件
• 高效的依賴解析器
• 智慧快取機制（第二次安裝幾乎是瞬間）
• 不需要啟動 Python 直譯器

九. 實戰：從零開始建一個資料分析專案

#

讓拍拍君帶你走一遍完整的流程：

# 1. 建立專案
uv init data-analysis
cd data-analysis

# 2. 指定 Python 版本
uv python pin 3.12

# 3. 加入資料分析套件
uv add pandas matplotlib seaborn scikit-learn

# 4. 加入 Jupyter（互動式分析好朋友）
uv add jupyter

# 5. 加入開發工具
uv add --dev ruff pytest ipykernel

# 6. 啟動 Jupyter Notebook
uv run jupyter notebook

整個過程不到 30 秒！以前光是 pip install pandas matplotlib seaborn scikit-learn jupyter 可能就要等好幾分鐘了。

建立分析腳本

#

# analysis.py
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns

# 載入範例資料
df = sns.load_dataset("penguins")

# 基本統計
print(df.describe())

# 視覺化
fig, axes = plt.subplots(1, 2, figsize=(12, 5))
sns.scatterplot(data=df, x="bill_length_mm", y="bill_depth_mm", 
                hue="species", ax=axes[0])
sns.boxplot(data=df, x="species", y="body_mass_g", ax=axes[1])
plt.tight_layout()
plt.savefig("penguins.png", dpi=150)
print("分析完成！圖表已存為 penguins.png")

執行：

uv run python analysis.py

就這麼簡單！

十. 從 pip / poetry 遷移

#

從 requirements.txt 遷移

#

# 建立 uv 專案
uv init
# 匯入現有依賴
uv add -r requirements.txt

從 poetry 遷移

#

如果你的專案有 pyproject.toml（poetry 格式），uv 可以直接讀取：

# uv 會自動辨識 pyproject.toml 中的依賴
uv sync

不過要注意，poetry 使用的 poetry.lock 和 uv 的 uv.lock 格式不同。第一次 uv sync 會重新解析依賴並生成 uv.lock。

保留 pip 相容模式

#

如果你不想全面遷移，uv 也提供完整的 pip 相容介面：

# 跟 pip 一模一樣的用法，但快 10-100 倍
uv pip install requests
uv pip install -r requirements.txt
uv pip freeze > requirements.txt
uv pip uninstall requests

漸進式遷移，毫無壓力！

十一. 常用指令速查表

#

結語

#

uv 真的是拍拍君目前最推薦的 Python 套件管理工具！用 Rust 寫的速度優勢太明顯了，而且它把 pip、venv、pyenv、pip-tools 的功能全部整合在一起，一個工具搞定所有事情。

最棒的是，uv 的學習曲線很平 —— 如果你會用 pip，你就幾乎會用 uv。但一旦用上了 uv add、uv run、uvx 這些現代化的指令，你就再也回不去了。

如果你的專案還在用 pip + venv 的傳統組合，或是覺得 poetry 太慢，強烈建議今天就試試 uv。

保證回不去 ⚡

延伸閱讀

#

• uv 官方文件
• Ruff（同家公司做的超快 Python linter）
• Python Typing 教學
• Python dotenv 教學
• Pydantic 教學