引言
如果你是一名 Python 开发者，可能已经被各种工具搞得晕头转向：pip、virtualenv、pipenv、poetry、pyenv... 每个工具都有自己的使用方式，学习成本很高。今天我要介绍的 uv 工具，可能会成为你的救星。
uv 是一个用 Rust 编写的极速 Python 包管理器和项目管理工具，它的目标是替代并统一多个 Python 工具的功能。最重要的是，它比传统工具快 10-100 倍！
什么是 uv？
uv 是由 Astral 团队开发的下一代 Python 工具链，它整合了以下功能：
包管理（替代 pip）
虚拟环境管理（替代 virtualenv）
Python 版本管理（替代 pyenv）
项目管理（替代 poetry）
工具管理（替代 pipx）
安装 uv
Windows
# 使用 PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
macOS 和 Linux
# 使用 curl
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者使用 pip（不推荐，但可用）
pip install uv
安装完成后，重启终端或运行 source ~/.bashrc（Linux/macOS）来更新环境变量。
验证安装：
uv --version
一、Python 项目管理
1.1 创建新项目
使用 uv 创建新项目非常简单：
# 创建一个新项目
uv init my-project
# 进入项目目录
cd my-project
这会创建以下文件结构：
my-project/
├── .python-version # Python 版本配置
├── pyproject.toml # 项目配置文件
├── README.md # 项目说明文件
└── src/
└── my_project/ # 源代码目录
└── __init__.py
1.2 管理 Python 版本
uv 可以自动管理项目的 Python 版本：
# 查看可用的 Python 版本
uv python list
# 为项目设置特定的 Python 版本
uv python pin 3.12
# 安装指定版本的 Python（如果本地没有）
uv python install 3.12
1.3 项目配置文件 (pyproject.toml)
uv 使用标准的 pyproject.toml 文件来管理项目配置：
[project]
name = "my-project"
version = "0.1.0"
description = "我的第一个 uv 项目"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
"requests>=2.31.0",
"pandas>=2.0.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.0.0",
"black>=23.0.0",
"mypy>=1.0.0",
]
1.4 运行项目
# 在项目环境中运行 Python
uv run python
# 运行 Python 脚本
uv run python my_script.py
# 运行项目中的模块
uv run -m my_project.main
二、包管理
2.1 添加依赖
# 添加生产依赖
uv add requests
uv add "pandas>=2.0.0"
# 添加开发依赖
uv add --dev pytest black mypy
# 添加可选依赖组
uv add --optional docs sphinx sphinx-rtd-theme
2.2 安装依赖
# 安装所有依赖
uv sync
# 只安装生产依赖
uv sync --no-dev
# 安装包括可选依赖
uv sync --all-extras
2.3 更新依赖
# 更新所有依赖到最新版本
uv lock --upgrade
# 更新特定的包
uv lock --upgrade-package requests
# 应用更新
uv sync
2.4 查看依赖
# 查看已安装的包
uv pip list
# 查看依赖树
uv pip tree
# 查看过时的包
uv pip list --outdated
2.5 锁定文件 (uv.lock)
uv 会自动生成 uv.lock 文件，确保团队成员使用相同版本的依赖：
# 生成/更新锁定文件
uv lock
# 根据锁定文件安装精确版本
uv sync
三、工具管理
3.1 全局工具安装
uv 可以像 pipx 一样管理全局 Python 工具：
# 安装工具
uv tool install ruff
uv tool install black
uv tool install httpie
# 列出已安装的工具
uv tool list
# 运行工具
uv tool run black --version
# 或者直接运行（如果在 PATH 中）
black --version
3.2 临时运行工具
无需安装即可运行工具：
# 临时运行工具
uvx ruff check .
uvx black --check .
uvx --from jupyter-core jupyter --version
3.3 工具升级和卸载
# 升级工具
uv tool upgrade ruff
uv tool upgrade --all
# 卸载工具
uv tool uninstall ruff
四、虚拟环境管理
4.1 创建虚拟环境
# 在当前项目中创建虚拟环境
uv venv
# 指定 Python 版本
uv venv --python 3.12
# 指定虚拟环境位置
uv venv .venv
4.2 激活虚拟环境
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
4.3 在虚拟环境中安装包
# 创建并激活虚拟环境后
uv pip install requests numpy pandas
五、程序发布
5.1 构建发布包
首先确保 pyproject.toml 配置正确：
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my-awesome-package"
version = "0.1.0"
description = "一个很棒的 Python 包"
authors = [
{name = "你的名字", email = "your@email.com"},
]
构建包：
# 构建 wheel 和 sdist
uv build
# 只构建 wheel
uv build --wheel
# 只构建 sdist
uv build --sdist
5.2 发布到 PyPI
# 安装发布工具
uv tool install twine
# 检查构建的包
uvx twine check dist/*
# 上传到 TestPyPI（测试）
uvx twine upload --repository testpypi dist/*
# 上传到 PyPI（正式发布）
uvx twine upload dist/*
5.3 创建可执行脚本
在 pyproject.toml 中配置入口点：
[project.scripts]
my-cli = "my_project.cli:main"
然后在代码中创建 CLI 入口：
# src/my_project/cli.py
def main():
print("Hello from my CLI!")
if __name__ == "__main__":
main()
5.4 发布前检查清单
更新版本号：在 pyproject.toml 中更新 version
运行测试：uv run pytest
代码格式化：uv run black .
类型检查：uv run mypy .
更新文档：确保 README.md 是最新的
构建测试：uv build
本地安装测试：uv pip install dist/*.whl
六、实用技巧和最佳实践
6.1 使用 .python-version 文件
在项目根目录创建 .python-version 文件：
3.12.0
uv 会自动使用指定版本的 Python。
6.2 配置 uv 的行为
创建 ~/.config/uv/config.toml：
# 使用国内镜像源
[index]
url = "https://pypi.doubanio.com/simple"
# 缓存设置
[cache]
dir = "~/.cache/uv"
6.3 集成 CI/CD
GitHub Actions 示例：
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v3
- name: Set up Python
run: uv python install
- name: Install dependencies
run: uv sync --all-extras
- name: Run tests
run: uv run pytest
6.4 常见问题解决
问题1：包冲突
# 查看冲突详情
uv pip check
# 强制重新安装
uv sync --reinstall
问题2：缓存问题
# 清理缓存
uv cache clean
问题3：锁定文件不同步
# 重新生成锁定文件
rm uv.lock
uv lock
七、从其他工具迁移
7.1 从 pip + requirements.txt 迁移
# 导入 requirements.txt
uv add -r requirements.txt
# 导入 dev-requirements.txt
uv add --dev -r dev-requirements.txt
7.2 从 Poetry 迁移
uv 可以直接读取 pyproject.toml，通常只需要：
# 在 Poetry 项目目录中
uv sync
7.3 从 Pipenv 迁移
# 导出 Pipenv 依赖
pipenv requirements > requirements.txt
# 导入到 uv
uv add -r requirements.txt
总结
uv 是一个强大而简单的 Python 工具，它统一了多个工具的功能，提供了极快的性能和良好的用户体验。对于 Python 初学者来说，掌握 uv 可以大大简化项目管理流程。
核心命令速查：
uv init - 创建新项目
uv add - 添加依赖
uv sync - 安装依赖
uv run - 运行命令
uv build - 构建包
uv tool - 管理全局工具
推荐工作流程：
使用 uv init 创建项目
使用 uv add 添加所需依赖
使用 uv run 运行和测试代码
使用 uv build 构建发布包
使用 uvx twine upload 发布到 PyPI
开始使用 uv，让你的 Python 开发之旅更加顺畅！