Python 包管理工具推荐：uv
目录
- 简介
- 安装 uv
- Python 版本管理
- 项目环境管理
- 依赖管理
- 运行代码
- 常用工作流
- 在 WSL 中使用 uv
- 常用命令速查
- 项目结构
- Git 版本控制
- 最佳实践
- 迁移指南
- 故障排查
- 总结
- 参考资源
简介
uv 是由 Astral 开发的超快速 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"
Git 版本控制
应该提交的文件
✅ 必须提交：
pyproject.toml- 项目配置和依赖声明uv.lock- 锁定依赖版本，确保团队环境一致.python-version- Python 版本固定文件（如果使用了uv python pin）
应该忽略的文件
❌ 必须忽略：
.venv/- 虚拟环境目录__pycache__/- Python 字节码缓存*.pyc- 编译的 Python 文件.pytest_cache/- pytest 缓存.ruff_cache/- ruff 缓存
.gitignore 模板
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
# 虚拟环境
.venv/
venv/
ENV/
env/
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# 测试和覆盖率
.pytest_cache/
.coverage
htmlcov/
.tox/
# Ruff
.ruff_cache/
# 操作系统
.DS_Store
Thumbs.db
# 构建产物
build/
dist/
*.egg-info/
为什么要提交 uv.lock？
提交 uv.lock 的好处：
- 环境一致性：团队成员、CI/CD、生产环境使用完全相同的依赖版本
- 可重现构建：任何时候都能精确重现当前环境
- 安全性：锁定版本可以避免依赖更新带来的意外问题
# 团队成员克隆项目后
git clone your-repo
cd your-repo
# 一条命令重现完全相同的环境
uv sync
# 所有人的依赖版本完全一致！
版本控制工作流
# 1. 添加新依赖
uv add requests
# 2. 查看变更
git status
# 会看到：
# modified: pyproject.toml
# modified: uv.lock
# 3. 提交两个文件
git add pyproject.toml uv.lock
git commit -m "feat: add requests dependency"
# 4. 推送到远程
git push
团队协作场景
其他成员拉取更新后：
# 拉取代码
git pull
# 同步依赖（自动使用 uv.lock）
uv sync
# 环境已更新，可以继续工作
uv run python main.py
最佳实践
- 始终使用
uv run：避免手动激活环境，减少出错 - 提交
uv.lock：确保团队依赖版本一致 .venv加入.gitignore：虚拟环境不应提交到版本控制- 开发依赖分离：使用
--dev标记开发工具 - 固定 Python 版本：使用
uv python pin确保团队版本一致 - 定期更新依赖：使用
uv sync --upgrade更新到兼容的最新版本 - 代码审查检查锁文件：确保依赖变更是有意为之
迁移指南
从 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 非常值得一试。
浙公网安备 33010602011771号