🐍 UV：新一代 Python 環境與包管理器使用指南
一、UV 是什么？
UV 是由 Astral 團隊開發的高性能 Python 環境管理器，旨在統一替代 pyenv、pip、venv、pip-tools、pipenv 等工具。
1.1 UV 的主要功能
- 🚀 極速包安裝（基于 Rust）
- 🧠 自動管理虛擬環境
- 🌀 Python 多版本支持與切換
- 📦 統一依賴管理（支持鎖文件）
- 🌍 全局 pip 安裝緩存共享
- 💼 開發 / 生產環境依賴分離
二、UV 使用入門
2.1 下載與安裝（https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_2）
💻 macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
🪟 Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
📦 Pip 安裝（不推薦，功能不全）
pip install uv
安裝完成后可用 uv --version 檢查是否安裝成功。
2.2 Python 版本管理
UV 支持下載并管理多個 Python 版本，類似于 pyenv。
查看已安裝的版本列表
uv python list
下載 Python 指定版本
uv python install 3.10
切換當前使用版本（pin)
uv python pin 3.10 #Pinned `.python-version` to `3.10`
? 切換后可立即使用對應版本的 Python 和環境進行項目初始化等操作。
2.3 初始化項目
建議先使用 uv python use 選擇好目標版本，然后再進行項目初始化。
創建新項目（使用當前選中的 Python 版本）
uv init my-project
cd my-project
或直接指定 Python 版本
uv init -p 3.11 awesome-project
初始化會自動生成：
.venv/目錄（項目虛擬環境）pyproject.toml（項目依賴聲明）uv.lock（鎖文件，鎖定精確依賴）
三、UV Init 創建項目的注意事項
3.1 推薦使用 uv add 管理依賴
uv add requests
uv add flask sqlalchemy
UV 不建議使用 pip install 安裝依賴，因為 UV 項目已默認隔離虛擬環境且依賴受鎖文件保護。
3.2 UV 項目的“無 pip 安裝”
UV 采用 全局 pip 緩存機制：
- 多個項目使用相同 Python 版本時，共享 pip 緩存，提高安裝效率
- 項目內并沒有傳統意義上的
pip install機制 - 因為 Python 版本一致 => pip 版本一致，避免 pip 被污染或沖突
uv.lock文件用于保證項目依賴一致性，可類比 npm 的package-lock.json
四、使用 UV 創建虛擬環境
初始化項目后，UV 自動為項目創建 .venv 虛擬環境，無需再手動 python -m venv。
如需手動創建虛擬環境：
#運行：
uv venv
#輸出：
#Using CPython 3.13.3
#Creating virtual environment at: .venv
#Activate with: .venv\Scripts\activate
激活方式與常規 .venv 一致：
# Windows cmd運行venv環境
.venv\Scripts\activate
#退出venv環境
deactivate
五、開發與生產環境管理
UV 區分了開發依賴與生產依賴：
5.1 添加開發依賴
uv add --dev black pytest isort
在 pyproject.toml 中會區分：
-
[dependency-groups] dev = ["black>=25.1.0","isort>=6.0.1","pytest>=8.3.5", ]
在 uv.lock 中
[package.metadata.requires-dev]
dev = [{ name = "black", specifier = ">=25.1.0" },{ name = "isort", specifier = ">=6.0.1" },{ name = "pytest", specifier = ">=8.3.5" },
]
5.2 鎖定依賴、部署同步
生成鎖文件（默認自動生成）：
uv lock
部署時安裝所有依賴：
uv pip sync
或僅安裝生產依賴：
uv pip sync --production
? 總結
| 功能 | UV 表現 |
|---|---|
| Python 多版本管理 | ? 支持 install/use/list |
| 虛擬環境 | ? 自動創建 .venv/ |
| 依賴管理 | ? 使用 pyproject.toml + uv.lock |
| 安裝效率 | 🚀 Rust 實現，遠快于 pip |
| 跨平臺 | ? 支持 macOS / Linux / Windows |
| 開發/生產區分 | ? 支持 --dev 與 --production |
UV = Python 開發的 Cargo，推薦前端 / 全棧 / 數據等開發者優先試用！
🧪 推薦實踐
uv python install 3.11
uv python pin 3.11
uv init -p 3.11 my-fastapi-app
cd my-fastapi-app
uv add fastapi uvicorn
uv add --dev black pytest
uv pip sync
