目录
- 简介
- 核心特性
- 安装 uv
- Linux / macOS / WSL
- Windows
- Python 版本管理
- 安装和管理 Python 版本
- 项目环境管理
- 为新项目创建环境
- 为已有代码创建环境
- 依赖管理
- 添加依赖
- 从已有依赖文件迁移
- 从 requirements.txt 导入
- 使用已有 pyproject.toml
- 运行代码
- 使用 uv run（推荐）
- 传统方式（激活环境）
- 直接使用环境 Python
- 常用工作流
- 场景 1：开始新项目
- 场景 2：接手已有项目（无依赖文件）
- 场景 3：接手有 requirements.txt 的项目
- 场景 4：多项目并行开发
- 在 WSL 中使用 uv
- 常用命令速查
- 项目管理
- 依赖管理
- Python 版本
- 查看信息
- 项目结构
- 最佳实践
- 迁移指南
- 从 pip + virtualenv 迁移
- 从 Poetry 迁移
- 从 Conda 迁移
- 故障排查
- 包安装失败
- 找不到包
- Python 版本问题
- 总结
- 参考资源
简介
uv 是超快速 Python 包管理器和项目管理工具，使用 Rust 编写，速度比 pip 快 10-100 倍。它不仅可以管理包依赖，还能管理多个 Python 版本和虚拟环境。
核心特性
- 极速安装：Rust 编写，包安装速度极快
- 多版本管理：轻松管理和切换不同 Python 版本
- 统一工具：集成包管理、环境管理、版本管理于一体
- 跨平台支持：完美支持 Linux、macOS、Windows 和 WSL
安装 uv
Linux / macOS / WSL
# 推荐方式
curl -LsSf https://astral.sh/uv/install.sh | sh# 或通过 pip
pip install uv
Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Python 版本管理
安装和管理 Python 版本
# 安装特定版本
uv python install 3.11
uv python install 3.12
uv python install 3.13# 查看已安装版本
uv python list# 查看可用版本
uv python list --all-versions# 设置项目默认版本
uv python pin 3.12
项目环境管理
为新项目创建环境
# 创建新项目
uv init myproject --python 3.11
cd myproject# 创建虚拟环境
uv venv# 添加依赖
uv add requests pandas numpy
为已有代码创建环境
# 在现有项目目录下
cd your_existing_project# 初始化 uv 项目（不会覆盖已有文件）
uv init# 创建虚拟环境
uv venv# 添加已知的依赖
uv add openai pandas numpy
依赖管理
添加依赖
# 添加运行时依赖
uv add package-name# 添加指定版本
uv add "openai==1.12.0"
uv add "pandas>=2.0.0"# 添加开发依赖
uv add --dev pytest black ruff# 添加可选依赖组
uv add --optional docs sphinx
从已有依赖文件迁移
从 requirements.txt 导入
# 方法 1：一次性导入到 pyproject.toml
cat requirements.txt | grep -v "^#" | grep -v "^$" | xargs uv add# 方法 2：只安装到环境（不修改 pyproject.toml）
uv pip install -r requirements.txt# 方法 3：逐个添加（更可控）
uv add openai pandas numpy
使用已有 pyproject.toml
# 自动读取并同步依赖
uv sync# 这会：
# 1. 读取 pyproject.toml 中的依赖
# 2. 创建/更新虚拟环境
# 3. 安装所有依赖
# 4. 生成 uv.lock 锁文件
运行代码
使用 uv run（推荐）
# 运行 Python 脚本
uv run python script.py# 运行模块
uv run python -m pytest# 启动交互式 Python
uv run python# 运行其他工具
uv run jupyter notebook
uv run flask run
uv run pytest tests/
优势：
- 无需手动激活环境
- 自动使用项目的虚拟环境和依赖
- 简洁高效
传统方式（激活环境）
# 激活虚拟环境
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows# 运行代码
python script.py# 退出环境
deactivate
直接使用环境 Python
# 不激活环境，直接调用
.venv/bin/python script.py
常用工作流
场景 1：开始新项目
# 创建项目
uv init my-app --python 3.12
cd my-app# 添加依赖
uv add fastapi uvicorn sqlalchemy# 添加开发工具
uv add --dev pytest black ruff# 运行项目
uv run python main.py
场景 2：接手已有项目（无依赖文件）
# 进入项目目录
cd existing-project# 初始化
uv init
uv venv# 尝试运行，根据报错添加依赖
uv run python main.py
# ModuleNotFoundError: No module named 'openai'# 添加缺失的包
uv add openai pandas# 继续运行
uv run python main.py
场景 3：接手有 requirements.txt 的项目
cd project-with-requirements# 初始化并导入依赖
uv init
uv venv
cat requirements.txt | grep -v "^#" | xargs uv add# 同步环境
uv sync# 运行项目
uv run python app.py
场景 4：多项目并行开发
# 项目 A - Python 3.11
cd project-a
uv init --python 3.11
uv add django# 项目 B - Python 3.12
cd ../project-b
uv init --python 3.12
uv add flask# 各自运行，互不干扰
cd ../project-a && uv run python manage.py runserver
cd ../project-b && uv run python app.py
在 WSL 中使用 uv
uv 在 WSL 环境中表现优异，与原生 Linux 体验一致：
# 安装
curl -LsSf https://astral.sh/uv/install.sh | sh# 使用方式完全相同
uv init myproject
uv add pandas numpy
uv run python script.py
WSL 优势：
- 性能优秀，安装速度极快
- 无缝集成 Windows 和 Linux 工作流
- 与 VS Code Remote 完美配合
常用命令速查
项目管理
uv init [project] # 初始化项目
uv venv # 创建虚拟环境
uv sync # 同步依赖
uv run <command> # 运行命令
依赖管理
uv add <package> # 添加依赖
uv add --dev <package> # 添加开发依赖
uv remove <package> # 移除依赖
uv pip install <package> # 直接安装（不更新配置）
uv pip list # 列出已安装包
Python 版本
uv python install <ver> # 安装 Python 版本
uv python list # 列出已安装版本
uv python pin <ver> # 固定项目版本
查看信息
uv run python --version # 查看项目 Python 版本
uv run which python # 查看 Python 路径
uv pip show <package> # 查看包信息
项目结构
使用 uv 管理的项目典型结构：
my-project/
├── .venv/ # 虚拟环境（可选加入 .gitignore）
├── pyproject.toml # 项目配置和依赖声明
├── uv.lock # 依赖版本锁定
├── src/ # 源代码
│ └── main.py
└── tests/ # 测试代码└── test_main.py
pyproject.toml 示例：
[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
requires-python = ">=3.11"
dependencies = ["openai>=1.0.0","pandas>=2.0.0","numpy",
][project.optional-dependencies]
dev = ["pytest>=7.0.0","black>=23.0.0","ruff>=0.1.0",
][build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
最佳实践
- 始终使用
uv run：避免手动激活环境，减少出错 - 提交
uv.lock：确保团队依赖版本一致 .venv加入.gitignore：虚拟环境不应提交到版本控制- 开发依赖分离：使用
--dev标记开发工具 - 固定 Python 版本：使用
uv python pin确保团队版本一致
迁移指南
从 pip + virtualenv 迁移
# 旧方式
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt# 新方式
uv venv
cat requirements.txt | xargs uv add
uv sync
从 Poetry 迁移
# Poetry 的 pyproject.toml 可以直接使用
uv sync# 或导出后导入
poetry export -f requirements.txt -o requirements.txt
cat requirements.txt | xargs uv add
从 Conda 迁移
# 导出 Conda 环境
conda list -e > requirements.txt# 用 uv 重建
uv init
cat requirements.txt | xargs uv add
故障排查
包安装失败
# 清除缓存重试
uv cache clean
uv sync
找不到包
# 验证包名
uv pip search <package-name># 或直接搜索 PyPI
Python 版本问题
# 查看当前版本
uv run python --version# 切换版本
uv python pin 3.12
uv venv --python 3.12
总结
uv 是新一代 Python 工具链的代表，它：
- 快：Rust 实现，速度远超传统工具
- 简：统一界面，一个工具管理所有
- 稳：锁文件机制，确保环境可复现
- 新：现代化设计，符合当前最佳实践
如果你厌倦了 pip、virtualenv、pyenv 的组合拳，或者想要更快的包管理体验，uv 是你的理想选择。
参考资源
- uv 官方文档
- GitHub 仓库
- PyPI 页面
最后更新：2025年10月
