UV 使用指南
UV 使用指南
UV 是一个用 Rust 编写的极速 Python 包管理器和项目管理工具。它不仅替代了 pip，还整合了 pip-tools、virtualenv、pyenv 甚至 poetry 的部分功能。
本指南将带你从项目初始化到高级依赖管理，全面掌握 UV 的核心用法。
🚀 核心优势速览
在开始之前，了解为什么你要切换到 UV：
- 极速：安装依赖比
pip快 10-100 倍。 - 零配置虚拟环境：自动创建和管理
.venv，无需手动source。 - Python 版本管理：内置
pyenv功能，一键安装任意 Python 版本。 - 标准兼容：完全遵循
pyproject.toml(PEP 621) 标准，兼容现有生态。 - 单一二进制：无需安装 Python 即可运行 UV（它自带运行时逻辑）。
1. 项目初始化 (Project Management)
UV 引入了“项目”概念，类似于 poetry 或 npm，通过 pyproject.toml 管理依赖。
创建新项目
uv init my-project
cd my-project
- 结果：生成
pyproject.toml、README.md、.python-version和一个默认的src/或main.py结构。 - 自动行为：UV 会自动检测或创建一个隔离的虚拟环境 (
.venv)。
指定 Python 版本初始化
如果你想让项目强制使用 Python 3.11：
uv init my-project --python 3.11
2. 依赖管理 (Dependency Management)
这是 UV 最常用的功能。你不再需要手动激活虚拟环境。
添加依赖
uv add requests pandas numpy
- 作用：安装包并更新
pyproject.toml和uv.lock(锁定文件)。 - 开发依赖：如果是测试工具或 lint 工具，使用
--dev标记：uv add --dev pytest ruff black
移除依赖
uv remove pandas
更新依赖
# 更新所有依赖到最新兼容版本
uv lock --upgrade
# 更新特定包
uv lock --upgrade-package requests
查看依赖树
uv tree
显示当前项目的依赖层级关系，帮助排查冲突。
3. 运行与脚本 (Running & Scripts)
UV 最大的亮点是无需激活虚拟环境即可运行代码。它会自动识别并使用项目内的 .venv。
运行 Python 脚本
uv run main.py
- 如果脚本需要参数：
uv run main.py --arg value - 如果未安装该 Python 版本，UV 会自动下载并临时使用。
运行命令行工具
直接运行已安装的 CLI 工具（如 pytest, ruff, django-admin）：
uv run pytest
uv run ruff check .
uv run python -m http.server
临时运行一次性命令 (类似 npx)
如果你不想把包添加到项目中，只想临时运行某个工具：
# 临时下载并运行 ruff，不写入项目依赖
uvx ruff check .
# 临时运行特定版本的 python 包
uvx --from httpie httpie http://example.com
注：uvx 是 uv run --with <package> 的快捷别名。
4. Python 版本管理 (替代 Pyenv)
UV 内置了 Python 安装器，不再需要单独安装 pyenv。
安装 Python 版本
# 安装 Python 3.12
uv python install 3.12
# 安装 Python 3.10 的特定小版本
uv python install 3.10.14
# 查看已安装的版本
uv python list
切换项目 Python 版本
在项目目录下，修改 .python-version 文件或运行：
uv python pin 3.11
下次运行 uv run 时，会自动使用该版本。
卸载 Python 版本
uv python uninstall 3.10
5. 高级用法与迁移
从 pip/requirements.txt 迁移
如果你有一个老项目只有 requirements.txt：
- 初始化项目：
uv init - 导入依赖：
UV 会解析所有包并生成标准的# 将 requirements.txt 中的包添加到 pyproject.toml uv add --requirements requirements.txtpyproject.toml和uv.lock。
导出为 requirements.txt
虽然推荐用 pyproject.toml，但如果需要兼容旧 CI/CD 流程：
uv export > requirements.txt
- 只导出生产依赖：
uv export --no-dev > requirements.txt
构建与发布包
如果你是库的作者：
# 构建分发包 (sdist 和 wheel)
uv build
# 发布到 PyPI (需配置 token)
uv publish
# 或者发布到测试源
uv publish --publish-url https://test.pypi.org/legacy/
6. 常用命令速查表
| 任务 | 传统命令 (pip/venv/pyenv) | UV 命令 |
|---|---|---|
| 创建虚拟环境 | python -m venv .venv |
uv venv (通常自动完成) |
| 激活环境 | source .venv/bin/activate |
不需要 (自动处理) |
| 安装包 | pip install requests |
uv add requests |
| 安装开发包 | pip install -r dev-reqs.txt |
uv add --dev pytest |
| 运行脚本 | python main.py (需先激活) |
uv run main.py |
| 安装 Python | pyenv install 3.12 |
uv python install 3.12 |
| 切换 Python | pyenv local 3.12 |
uv python pin 3.12 |
| 显示依赖树 | pipdeptree |
uv tree |
| 清理缓存 | pip cache purge |
uv cache clean |
| 自更新 | pip install -U uv |
uv self update |
7. 配置文件详解 (pyproject.toml)
UV 使用标准的 pyproject.toml。一个典型的配置如下：
[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
requires-python = ">=3.11"
dependencies = [
"requests>=2.31.0",
"fastapi>=0.109.0",
]
[project.optional-dependencies]
dev = [
"pytest>=8.0.0",
"ruff>=0.1.0",
]
[tool.uv]
# UV 特有配置
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple" # 国内镜像源
💡 最佳实践提示
- 提交
uv.lock：务必将uv.lock文件提交到 Git。它确保了团队成员和 CI 环境安装的依赖版本完全一致（类似package-lock.json或Poetry.lock）。 - 不要提交
.venv：在.gitignore中确保包含.venv/。 - 国内加速：如果下载慢，可以在
pyproject.toml中配置[tool.uv]的index-url，或者在使用uv add时临时指定：uv add requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple - CI/CD 集成：在 GitHub Actions 等环境中，只需安装 uv 并运行
uv sync即可快速还原环境，速度极快。- name: Install uv uses: astral-sh/setup-uv@v3 - name: Install dependencies run: uv sync --frozen
❓ 常见问题
Q: uv run 和直接 python 有什么区别？
A: uv run 会确保在项目的隔离环境中运行，自动处理依赖路径和 Python 版本。直接使用 python 可能会用到全局环境或错误的虚拟环境。
Q: 我可以同时使用 pip 和 uv 吗？
A: 可以，但不推荐混用。如果在同一个虚拟环境中混用，可能会导致 uv.lock 与实际环境不一致。建议在一个项目中统一使用 UV。
Q: 如何卸载 UV？
A: 运行 uv self uninstall。如果是通过 pip 安装的，则用 pip uninstall uv。
最后更新：2026-03-15 | 适用版本：UV 0.6+
浙公网安备 33010602011771号