🐍 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
