使用 uv 建立 Python 專案環境

發表於 更新於 分類於

使用 uv 建立 Python 專案環境：快速、乾淨、可重現

uv 是由 Astral 開發的超高速 Python 工具，可取代 pip, venv, pyenv, poetry 的安裝、建立虛擬環境、Python 版本管理、專案管理等功能，支援 pyproject.toml 的依賴管理，是現代化 Python 專案環境建置的利器。

這篇筆記整理了使用 uv 建立虛擬環境、安裝套件、管理依賴的完整流程，適合給想建立 快速、可重現、乾淨的 Python 開發環境 的工程師參考。

🛠 安裝 uv

pip install uv

或使用 Homebrew (macOS/Linux)：

brew install astral-sh/tap/uv

🚀 建立 Python 專案環境流程

uv init .
uv venv
uv add django

步驟說明：

指令 功能說明
uv init . 初始化 pyproject.toml，設定專案 metadata
uv venv 建立虛擬環境 .venv
uv add django 安裝 Django 並加入 pyproject.toml + uv.lock

✅ 安裝的套件會被記錄到 pyproject.toml 中，並且自動鎖定到 uv.lock，確保環境重現性。

✅ 常用 uv 指令總覽

功能 指令範例 說明
安裝套件 uv add requests 加入正式依賴
安裝 dev 套件 uv add --dev ruff 加入開發用依賴（如 Linter）
查看已安裝套件 uv pip list 顯示虛擬環境內的套件
執行 Python 程式 uv run python app.py 使用虛擬環境執行程式
移除套件 uv remove requests 從依賴清單和虛擬環境中移除套件
同步環境 uv sync 根據 lock 檔安裝所有依賴

🔄 清除並重建虛擬環境

如果想清除多餘的依賴或重建乾淨環境：

rm -rf .venv uv.lock
uv venv
uv sync

這會根據目前 pyproject.toml 重建乾淨環境，不殘留任何「孤兒套件」。

🐍 指定 Python 版本（選擇性）

檢查可安裝哪些 Python 版本並安裝

uv python list
uv python install 3.12

切換 Python 版本

uv python pin 3.12

# pyproject.toml
[project]
requires-python = ">=3.10"

如需使用指定的 Python 安裝版本建構 .venv，可這樣設定：

PYTHON=/usr/local/bin/python3.10 uv venv

比較 pyenv 跟 uv 兩種 Python 版本管理

工具 用途 影響範圍
pyenv 控制 整個系統或目錄的 Python 版本 全域或目錄切換
uv 在虛擬環境中自動管理 Python 版本 只限 .venv

🧪 執行與開發（不用手動 activate 虛擬環境！）

uv run python manage.py runserver  # 執行 Django 開發伺服器
uv run pytest                      # 執行測試

uv run 會自動使用 .venv/bin/python，不需手動 source .venv/bin/activate

📌 範例 pyproject.toml

[project]
name = "my-uv-app"
version = "0.1.0"
description = "A Python app using uv for dependency management"
requires-python = ">=3.10"

[tool.uv.dependencies]
django = "*"

[tool.uv.dev-dependencies]
ruff = "*"

指令比較

動作 會寫入 pyproject.toml 會更新 uv.lock 安裝到虛擬環境
uv add flask ✅ 是 ✅ 是 ✅ 是
uv pip install ❌ 否 ❌ 否 ✅ 是
uv lock ❌ 否 ✅ 是（根據 pyproject.toml） ❌ 否
uv sync ❌ 否 ❌ 否 ✅ 是（根據 uv.lock）

🧠 小結

  • uv 是快速又現代的 Python 專案工具。
  • 和 pip 不同，uv add 是管理專案依賴，自動記錄與鎖定。
  • 搭配 pyproject.toml + uv.lock 可以輕鬆建立 一致可重現 的環境。
  • uv run 取代虛擬環境的啟動/關閉流程，開發更方便。