uv 是一个极快的 Python 包和项目管理工具,用 Rust 编写。它可以用来安装 Python、创建虚拟环境、管理依赖、运行脚本,还提供了类似 pip 的兼容接口。
| 需求 | uv 的做法 | 好处 |
|---|---|---|
| 创建项目 | uv init |
快速生成项目结构 |
| 安装依赖 | uv add |
自动更新锁定文件 |
| 运行命令 | uv run |
不用手动激活环境 |
| 管理 Python | uv python |
统一安装和切换版本 |
| 临时使用工具 | uvx |
即用即走,不污染环境 |
提示:如果你之前习惯使用
pip、venv或poetry,可以把uv看作一个更快、更统一的工具链。
macOS 和 Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv --version
如果能看到版本号,说明安装成功。
uv init hello-uv
cd hello-uv
执行后,uv 会帮你生成一个基础项目。
一个典型的 uv 项目通常会包含:
| 文件/目录 | 作用 |
|---|---|
pyproject.toml |
项目配置和依赖声明 |
.python-version |
锁定 Python 版本 |
README.md |
项目说明 |
main.py |
示例入口文件 |
注意:
.venv/通常会在你执行uv sync或uv run之后才创建,不会在uv init后立刻出现。
这是新手最常见的使用流程:
uv init hello-uv
cd hello-uv
uv add requests
uv run main.py
这一步的目的,是让你先把依赖装进项目里,再用项目环境运行代码。
如果你想马上看到依赖生效,可以把 main.py 改成下面这样:
import requests
def main():
print(requests.__version__)
if __name__ == "__main__":
main()
执行 uv run 时,uv 会按项目环境运行命令,并在需要时安装或更新依赖;如果需要的 Python 版本还没安装,也会自动下载。
注意:
uv默认会优先围绕pyproject.toml管理项目。
uv add requests
这会同时完成两件事:
uv add --dev pytest
开发依赖通常用于测试、格式化、检查等场景。
uv remove requests
uv sync
这个命令会根据锁定文件和项目配置同步环境,适合在拉取代码后重建本地环境。
uv run main.py
uv run 会按项目环境运行命令,不需要你手动执行 source .venv/bin/activate。
如果你只是想快速试一段代码,可以直接用 uv run:
uv run python -c "print('hello uv')"
对于单文件脚本,uv 也可以管理脚本依赖:
uv add --script demo.py requests
uv run demo.py
这会把依赖写进脚本头部的内联元数据中,例如:
# /// script
# dependencies = ["requests"]
# ///
import requests
脚本依赖和项目依赖是分开的,更适合临时脚本。
uv venv
创建后,默认会生成 .venv 目录。
uv venv --python 3.12
uv python install 3.11 3.12
uv python pin 3.12
这个命令会写入 .python-version,方便团队统一版本。
uvx ruff --version
uvx 适合快速试用命令行工具,不需要长期安装。
如果你还想保留 pip 的使用习惯,可以用:
uv pip install requests
uv pip list
提示:新项目优先用
uv add和uv sync,迁移旧项目时再重点看uv pip接口。
因为 uv run 会自动在项目环境中执行命令,减少了环境切换成本。
uv add 和 uv pip install 有什么区别| 命令 | 适用场景 |
|---|---|
uv add |
新项目或 pyproject.toml 管理的项目 |
uv pip install |
兼容旧的 pip 工作流 |
建议同时提交这些文件:
| 文件 | 作用 |
|---|---|
pyproject.toml |
声明项目和依赖 |
uv.lock |
锁定依赖版本 |
.python-version |
固定 Python 版本 |
| 目标 | 命令 |
|---|---|
| 安装 uv | curl -LsSf https://astral.sh/uv/install.sh 后执行 sh |
| 初始化项目 | uv init demo |
| 添加依赖 | uv add requests |
| 安装开发依赖 | uv add --dev pytest |
| 运行脚本 | uv run main.py |
| 创建虚拟环境 | uv venv |
| 安装 Python | uv python install 3.12 |
| 固定版本 | uv python pin 3.12 |
| 临时运行工具 | uvx ruff --version |