什么是 UV？
UV 是一个用 Rust 编写的快速 Python 包管理器和虚拟环境工具，旨在提供比 pip 和 venv 更快的速度和更简洁的体验。
速度极快
比 pip 快 10-100 倍，尤其在处理大量依赖时
自动管理
无需手动创建和激活虚拟环境，简化工作流
确定性构建
通过 uv.lock 确保环境一致性，消除"在我机器上能运行"问题
安装 UV
UV 提供了多种安装方式，适用于不同操作系统：
通用安装脚本（推荐）
使用 pip 安装（备用）
Windows 系统（PowerShell）
验证安装
升级 UV 到最新版本
初始化项目
创建并初始化一个新的 Python 项目：
创建项目目录并进入
初始化项目（生成 pyproject.toml）
该命令会生成基础的 pyproject.toml 文件，包含项目元信息和依赖管理配置。
设置镜像源（index-url）
为了加速包下载，可以配置国内镜像源：
临时使用
全局配置（推荐）
通过环境变量设置：
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# Linux/macOS（bash/zsh）永久生效
echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.bashrc
source ~/.bashrc
$env:UV_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"
# Windows PowerShell 永久生效
[Environment]::SetEnvironmentVariable("UV_INDEX_URL", "https://pypi.tuna.tsinghua.edu.cn/simple", "User")
虚拟环境管理
UV 会自动管理虚拟环境，无需手动创建：
创建虚拟环境
uv venv
# 创建指定大版本的虚拟环境（会使用该系列最新版本）
uv venv --python 3.11
# 创建指定精确版本的虚拟环境
uv venv --python 3.10.12
激活虚拟环境
Linux/macOS
Windows (PowerShell)
退出虚拟环境
查看虚拟环境信息
uv run python --version
# 查看虚拟环境详细信息
uv venv --info
依赖管理
添加依赖
uv add requests # 最新版本
uv add pandas==2.1.0 # 指定版本
uv add "flask>=2.0.0" # 版本范围
# 添加开发依赖（仅开发环境使用）
uv add --dev pytest
uv add --dev black isort # 同时添加多个
注意：增加依赖时不需要激活环境，UV会自动使用项目的虚拟环境。
移除依赖
uv remove requests
# 移除开发依赖
uv remove --dev pytest
同步依赖
uv sync
# 强制重新生成锁文件并同步
uv sync --force
导出依赖（兼容 pip）
uv export > requirements.txt
# 导出开发依赖
uv export --dev > requirements-dev.txt
查看已安装的依赖
uv list
# 查看特定依赖的详细信息
uv list requests
# 以树形结构查看依赖关系
uv tree
常用命令补充
-
uv install安装锁文件中的所有依赖 -
uv update更新所有依赖 -
uv update requests更新指定依赖 -
uv check检查依赖冲突 -
uv cache clean清理缓存
从 requirements.txt 转换为 pyproject.toml
将现有的 requirements.txt 转换为 UV 所使用的 pyproject.toml 格式非常简单，UV 提供了专门的命令来实现这一转换。
1. 准备工作
确保你已经在项目目录中（如果是新项目，可先通过 uv init 初始化生成基础的 pyproject.toml），并将 requirements.txt 放在项目根目录下。
2. 导入生产依赖
使用 uv add 命令直接从 requirements.txt 导入依赖：
3. 导入开发依赖
如果有单独的开发环境依赖文件（如 requirements-dev.txt）：
4. 验证转换结果
打开 pyproject.toml 查看是否正确导入：
name = "my_project"
version = "0.1.0"
dependencies = [
"requests==2.31.0",
"pandas>=2.0.0",
]
[project.optional-dependencies]
dev = [
"pytest==7.4.0",
"black>=23.0",
]
5. 生成锁文件并同步环境
注意事项
- 如果 requirements.txt 中包含 URL 形式的依赖（如 git 仓库地址），UV 也能正确识别并导入。
- 若依赖项存在版本冲突，UV 会在转换过程中提示错误，需手动解决冲突后再重新执行导入命令。
- 转换后，建议删除原 requirements.txt 或标记为过时（如重命名为 requirements.txt.old），避免后续维护时出现两份依赖清单不一致的问题。
补充内容
使用 UV 运行 Python 脚本
方法一：使用 uv run 命令（推荐）
uv run main.py
# 传递命令行参数
uv run main.py --arg1 value1 --arg2 value2
# 运行模块（如 Python 的 -m 选项）
uv run -m mymodule.submodule
方法二：手动调用虚拟环境中的 Python 解释器
.venv/bin/python main.py
# Windows (PowerShell)
.venv\Scripts\python.exe main.py
创建多个不同版本的虚拟环境
1. 为不同项目创建不同版本的虚拟环境
mkdir project-a && cd project-a
uv venv --python 3.10 # 创建 Python 3.10 的虚拟环境
cd ..
# 项目 B 使用 Python 3.12
mkdir project-b && cd project-b
uv venv --python 3.12 # 创建 Python 3.12 的虚拟环境
cd ..
2. 为同一项目创建多个不同版本的虚拟环境（指定路径）
cd my-project
# 创建 Python 3.10 的虚拟环境（路径为 .venv-3.10）
uv venv --python 3.10 .venv-3.10
# 创建 Python 3.11 的虚拟环境（路径为 .venv-3.11）
uv venv --python 3.11 .venv-3.11
# 创建 Python 3.12 的虚拟环境（路径为 .venv-3.12）
uv venv --python 3.12 .venv-3.12
3. 使用指定版本的虚拟环境
uv run --venv .venv-3.10 main.py
# 使用 Python 3.12 环境安装依赖
uv add requests --venv .venv-3.12
删除虚拟环境
UV 生成的虚拟环境本质上是项目目录中的一个文件夹，只需删除对应的文件夹即可：
删除默认虚拟环境（.venv）
Linux/macOS 终端
cd your-project
# 删除默认虚拟环境文件夹
rm -rf .venv
Windows PowerShell
cd your-project
# 删除默认虚拟环境文件夹
Remove-Item -Recurse -Force .venv
删除自定义路径的虚拟环境
rm -rf .venv-3.11
# 删除名为 py312-env 的虚拟环境（Windows PowerShell）
Remove-Item -Recurse -Force py312-env
注意事项
删除虚拟环境会彻底清除该环境中安装的所有依赖和 Python 解释器，操作不可逆，请谨慎执行。 如果需要重新使用该环境，只需重新创建即可。