uv：统一的 Python 包管理

△△请给“Python猫”加星标 ，以免错过文章推送

花下猫语：uv 项目自发布起就大受欢迎，目前 Github star 52.6 K，远超过它的同类竞品们。前不久，它的创始人在 X 上披露了一组惊人的数据：uv 曾占据了 PyPI 超过 20% 的流量，用户每天通过它发起约 4-5 亿次下载请求！

我在去年翻译过 uv 首发时的新闻文章[1]，根据博客后台不完整的统计，从 Google 搜索进入的访问量已经超过 3000，妥妥成为了我博客的搜索访问 TOP 1！这侧面也反映出 uv 的火爆程度！

uv 刚过一周岁不久，如此年轻，成绩斐然啊。趁着这波热点（实际是假期有时间），我抽空把 uv 重要版本更新的文章也翻译出来了，enjoy reading～

作者：@charliermarsh[2]

译者：豌豆花下猫@Python猫

英文：uv: Unified Python packaging (https://astral.sh/blog/uv-unified-python-packaging)

声明：本翻译是出于交流学习的目的，为便于阅读，部分内容略有改动。转载请保留作者信息。

简述：uv是一个用 Rust 开发的超高性能 Python 包管理器。

我们最初在 2 月份发布了 uv，作为常见pip工作流的即插即用替代方案。（译注：uv 在 2024.02 发布，本文写于 2024.08，翻译于 2025.05）

今天，我们发布一系列新功能，这些功能将 uv 从一个pip替代品扩展成为一个端到端的解决方案，可用于管理 Python 项目、命令行工具、单文件脚本，甚至 Python 本身。

它就像是 Python 世界的Cargo：提供了一个快速、可靠且易用的统一接口。

在 Astral，我们致力于为 Python 生态系统打造高性能的开发工具。我们最知名的产品是 Ruff[3]，一个超高速的 Python 代码检查器[4] 和 格式化工具[5]。

在 2 月份，我们发布了 uv，这是一个极快的 Python 包安装器和依赖解析器[6]，最初设计为常见pip工作流的即插即用替代方案。【】

今天，我们宣布 uv 自首次发布以来最大规模的功能扩展：

• 端到端项目管理 [7] ：uv run、uv lock和uv sync。uv 现在能基于标准元数据创建跨平台的锁文件，并利用该文件来安装依赖。它是 Poetry、PDM 和 Rye 等工具的高性能替代品。

• 工具管理 [8] ：uv tool install和uv tool run(别名为uvx)。uv 能在隔离的虚拟环境中安装命令行工具，还能无需先安装就直接执行命令（如uvx ruff check）。它是pipx等工具的高性能替代品。

• Python 安装 [9] ：uv python install。uv 现在可以直接帮你安装 Python，替代pyenv等工具。

• 脚本执行 [10] ：uv 现在可以管理基于 PEP 723 [11] 标准的单文件 Python 脚本，这些脚本内部包含依赖元数据。只需要一个简单的uv run命令就能执行这些独立的 Python 脚本。

...所有功能背后都是一个跨平台的超高速依赖解析器在支撑。

上图展示了启用所有可选依赖项时解析 Transformers[12] 项目的速度对比：上方无缓存状态，下方启用了缓存。

并且所有功能都包含在新的、全面的文档中。

这些新功能每一项都大大扩展了 uv 的能力范围。但更独特的是，它们组合起来形成了一个完整的工具链，大大简化了 Python 开发过程。

结合uv pip（我们将它作为一等功能，继续维护并改进），uv 适用于任何 Python 工作流，从一次性脚本到大型的多包工作区开发。

你可以通过我们的独立安装程序或从 PyPI 安装 uv：

curl

curl -LsSf https://astral.sh/uv/install.sh | sh

win

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

pip

pip install uv

pipx

pipx install uv

uv 现在可以全面管理 Python 项目了。如果你用过 Poetry、PDM 或 Rye，那么 uv 的项目 API 对你来说一定不陌生。

项目 API 基于 Python 标准构建，使用pyproject.toml来定义项目元数据。

例如，你可以运行uv init && uv add "fastapi>=0.112"生成以下内容：

[project] name = "hello-world" version = "0.1.0" readme = "README.md" dependencies = ["fastapi>=0.112"]

从它开始，uv 将基于项目的依赖项创建一个锁文件。以下是一个示例片段：

[[package]] name = "fastapi" version = "0.112.1" source = { registry = "https://pypi.org/simple" } dependencies = [     { name = "pydantic" },     { name = "starlette" },     { name = "typing-extensions" }, ] sdist = { url = "https://files.pythonhosted.org/packages/2c/09/71a961740a1121d7cc90c99036cc3fbb507bf0c69860d08d4388f842196b/fastapi-0.112.1.tar.gz", hash = "sha256:b2537146f8c23389a7faa8b03d0bd38d4986e6983874557d95eed2acc46448ef", size = 291025 } wheels = [     { url = "https://files.pythonhosted.org/packages/39/b0/0981f9eb5884245ed6678af234f2cbcd40f44570718caddc0360bdb4015d/fastapi-0.112.1-py3-none-any.whl", hash = "sha256:bcbd45817fc2a1cd5da09af66815b84ec0d3d634eb173d1ab468ae3103e183e4", size = 93163 }, ] [[package]] name = "fastapi-cli" version = "0.0.5" source = { registry = "https://pypi.org/simple" } dependencies = [     { name = "typer" },     { name = "uvicorn", extra = ["standard"] }, ] sdist = { url = "https://files.pythonhosted.org/packages/c5/f8/1ad5ce32d029aeb9117e9a5a9b3e314a8477525d60c12a9b7730a3c186ec/fastapi_cli-0.0.5.tar.gz", hash = "sha256:d30e1239c6f46fcb95e606f02cdda59a1e2fa778a54b64686b3ff27f6211ff9f", size = 15571 } wheels = [     { url = "https://files.pythonhosted.org/packages/24/ea/4b5011012ac925fe2f83b19d0e09cee9d324141ec7bf5e78bb2817f96513/fastapi_cli-0.0.5-py3-none-any.whl", hash = "sha256:e94d847524648c748a5350673546bbf9bcaeb086b33c24f2e82e021436866a46", size = 9489 }, ]

uv 的锁文件就像项目依赖关系的完整快照，它能确保项目在不同机器上的运行环境保持一致。

这个锁文件最大的优势是跨平台。不管你在哪个系统上生成锁文件，它都能在其它平台上正常工作。uv 为每个平台定义了一个独特的解决方案，生成一个可读且可审计的锁文件，精确地定义了将安装哪些软件包。

例如：如果你在 macOS 上运行uv lock，uv 仍然会为 Linux 和 Windows 生成解析方案，即使每个平台上所需的依赖集稍有不同。

而且它做得非常快。在没有任何缓存的情况下，uv 可以在大约半秒钟内解析 Jupyter 项目的依赖项（在缓存预热的情况下约为 20 毫秒）。

解析 Jupyter 项目时无缓存（上）和有缓存（下）的对比。

项目 API 的核心是uv run命令，它能在项目专属环境中运行命令，而且不需要手动激活虚拟环境。

uv run非常快速。每次执行时，它都会自动重新锁定和同步项目，确保你的环境始终是最新状态。完全不需要手动干预。

换句话说，uv run能确保你的命令每次都在一个一致的、受锁文件管理的环境中运行。

使用uv run命令启动 FastAPI 应用的示例。

有了uv run，你再也不需要操心虚拟环境的激活、依赖包的管理或者项目的维护更新。一切都变得无比简单。

想了解更多详情，请查阅项目文档[13]。

本文翻译并首发于 Python猫：https://pythoncat.top/posts/2025-05-05-uv

uv 基于 Python 标准构建，如 PEP 621[14]。同时，它还添加了一些在标准中没有的功能，这些功能对本地开发至关重要，如相对路径和可编辑依赖。

在标准的project.dependencies部分，你可以定义项目的依赖和可发布的元数据。而在开发过程中，uv 还允许你通过tool.uv.sources为这些依赖项指定替代来源。

例如，要使用本地的、可编辑版本的anyio，你可以运行uv add --editable ../anyio来生成以下pyproject.toml：

[project] name = "hello-world" version = "0.1.0" readme = "README.md" dependencies = ["anyio"] [tool.uv.sources] anyio = { path = "../anyio", editable = true }

当发布到 PyPI 时，上述包会声明对anyio的依赖。但在本地开发时，使用uv run可以将../anyio路径下的可编辑的包加到开发环境中。这样，项目的依赖定义保持不变，只是依赖的来源发生了变化。

详细内容请查阅依赖源文档[15]。

工作区

受 Cargo 相同概念[16]的启发，uv 支持工作区：一组管理在一起的包的集合。

想象这样一个场景：在同一个 Git 仓库中，有一个使用 FastAPI 构建的 Web 应用，还有多个作为独立 Python 包开发和维护的库。

大多数大型 Python 项目最终都会用自己的方式来实现这个概念，它们通常借助手写脚本和自定义工具来管理各个包之间的关系。

uv 的工作区 API 为大规模开发中的各种挑战提供了一致、高效且具有创新性的解决方案。

在工作区中，每个包都有自己的pyproject.toml，但工作区共享一个锁文件，确保工作区使用一致的依赖集运行。

[project] name = "fastapi" version = "0.1.0" readme = "README.md" dependencies = ["uvicorn"] [tool.uv.sources] uvicorn = { workspace = true } [tool.uv.workspace] members = ["libraries/*"]

在工作区的根目录下，你可以运行命令来操作任何工作区包。例如，执行uv run --package fastapi或uv run --package uvicorn。

更多细节，请查阅工作区文档[17]。

工具

uv 现在有两种新能力：

• 通过uv tool install在专用的隔离虚拟环境中安装命令行工具（如 Ruff）

• 通过uvx直接运行一次性命令，无需预先安装

如果你使用过 pipx[18] 或 npx[19]，你会发现 uv 的工具 API 很熟悉。

比如，输入uvx posting就能直接运行 Darren Burns 开发的posting终端界面程序（TUI）。

使用uvx命令在终端中运行 posting 的示例。

工具 API 让你能集中管理系统上的 Python 工具。你可以：

• 用uv tool list查看所有已安装的工具及其可执行文件

• 用uv tool upgrade --all将所有工具升级到最新版本

uv 的工具 API 非常快，通过uvx执行命令几乎没有任何额外开销。

更多工具功能，请查阅工具文档[20]。

Python 引导安装

uv 现在能够安装和管理 Python 本身，使其完全自引导：

$ curl -LsSf https://astral.sh/uv/install.sh | sh $ uv python install 3.12

如果你的机器上没有安装 Python，或者缺少特定的、所需的 Python 版本，除了显式调用uv python外，uv 还可以根据需要，自动下载所需的 Python 版本（如uv run、uv venv等命令）。

例如，以下是在新的 Ubuntu Docker 镜像上运行 posting 所需的全部命令，没有任何隐藏步骤：

$ apt-get update && apt-get install -y curl $ curl -LsSf https://astral.sh/uv/install.sh | sh $ source $HOME/.cargo/env $ uvx posting

当你运行 uvx 命令时，uv 会一步到位地完成所有工作：

• 安装 Python 3.12.4（文章写作时的最新稳定版本）

• 创建虚拟环境

• 安装必要的依赖包

• 启动 posting 程序

整个过程无缝衔接，高效快捷。

单文件脚本

最后：uv 现在提供了对单文件 Python 脚本的一等支持，这些脚本可以内嵌依赖元数据，完全符合 PEP-723 标准。

例如，以下文件 main.py，它从 Python 增强提案索引中获取前 10 个 PEP：

import requests from rich.pretty import pprint resp = requests.get("https://peps.python.org/api/peps.json") data = resp.json() pprint([(k, v["title"]) for k, v in data.items()][:10])

这个脚本依赖requests和rich，但不包含任何显式的依赖元数据。早些时候，你需要单独管理这些依赖项，例如使用专门的 requirements.txt 文件。

现在，你可以使用uv add自动将依赖声明嵌入到脚本中：

$ uv add --script main.py "requests<3" "rich" $ cat main.py # /// script # requires-python = ">=3.12" # dependencies = [ #     "requests<3", #     "rich", # ] # /// import requests from rich.pretty import pprint resp = requests.get("https://peps.python.org/api/peps.json") data = resp.json() pprint([(k, v["title"]) for k, v in data.items()][:10])

有了它，uv run main.py将在一个隔离的、临时的虚拟环境中执行脚本，并安装所有依赖项。

使用 uv run 执行带有内嵌依赖项的单文件脚本的示例。

你也可以使用--with标记在运行时指定依赖项，例如：uv run --with "requests<3" --with rich main.py。

有了 uv 的 Python 引导安装功能，你只需要 uv 就可以运行封闭式的、可重分发的单文件 Python 脚本，再也不用担心虚拟环境、包管理或 Python 版本的问题。

更多细节，请查阅脚本文档[21]。

为规模化而构建

在 Astral，我们的指导原则之一是：“为所有人设计，为规模化构建（Design for everyone, build for scale）。”

我们希望打造的工具对初学者友好，但同时又能满足最大型 Python 项目的需求。

我们相信 uv 已经很好地实现了这两个目标。

如果你在组织里使用 uv，并想一起解决 Python 生态的包管理挑战，欢迎联系我们。让我们携手共创更好的工具。

附录

参考资料

新闻文章: https://pythoncat.top/posts/2024-03-05-uv

@charliermarsh: https://twitter.com/charliermarsh

Ruff: https://github.com/astral-sh/ruff

代码检查器: https://notes.crmarsh.com/python-tooling-could-be-much-much-faster

[5]

格式化工具: https://astral.sh/blog/the-ruff-formatter

[6]

Python 包安装器和依赖解析器: https://pythoncat.top/posts/2024-03-05-uv

[7]

端到端项目管理: https://docs.astral.sh/uv/concepts/projects/

[8]

工具管理: https://docs.astral.sh/uv/concepts/tools/

[9]

Python 安装: https://docs.astral.sh/uv/concepts/python-versions/

[10]

脚本执行: https://docs.astral.sh/uv/guides/scripts/

[11]

PEP 723: https://peps.python.org/pep-0723/

[12]

Transformers: https://github.com/huggingface/transformers

[13]

项目文档: https://docs.astral.sh/uv/concepts/projects/

[14]

PEP 621: https://peps.python.org/pep-0621/

[15]

依赖源文档: https://docs.astral.sh/uv/concepts/dependencies/#dependency-sources

[16]

Cargo 相同概念: https://doc.rust-lang.org/cargo/reference/workspaces.html

[17]

工作区文档: https://docs.astral.sh/uv/concepts/workspaces/

pipx: https://github.com/pypa/pipx

npx: https://docs.npmjs.com/cli/v8/commands/npx

工具文档: https://docs.astral.sh/uv/concepts/tools/

[21]

脚本文档: https://docs.astral.sh/uv/guides/scripts/

如果你正在寻找优质的Python文章和项目，我必须向你推荐Python潮流周刊！

它精选全网的优秀文章、教程、开源项目、软件工具、播客、视频、热门话题等丰富内容，让你紧跟技术最前沿，获取最新的第一手学习资料！

欢迎点击下方图片，了解这份全世界知识密度最高、知识广度最大的 Python 技术周刊。