uv：十年间 Python 生态最伟大的革新

一句话概括：uv 是一个用 Rust 编写的神速 Python 包与环境管理器，彻底简化了 Python 安装、虚拟环境和依赖同步流程。

2025 年了，安装 Python、管理虚拟环境、在同事之间同步依赖，真的有必要这么痛苦吗？答案是：不！最近出现了一个名为 uv 的杰出新工具，它彻底改变了安装和使用 Python 的便捷程度。

uv 是由 Astral 这家小型初创公司开发的免费开源工具。过去几年里，Astral 一直致力于打造高质量的 Python 工具（比如广受好评的 linter——Ruff）。uv 能做的事情包括：

• 帮你安装任意版本的 Python
• 安装包
• 管理虚拟环境
• 以极快的速度解决依赖冲突（对大型项目至关重要）

最棒的是，在我看来，它能在上述所有方面都做得比任何其他工具都好。它速度惊人，用 Rust 编写，几乎能在所有操作系统或平台上运行。

安装 uv

安装 uv 很简单。有几种方法，但最简单的（就我而言）是这个单行命令——Linux 和 Mac 上：

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

Windows 上（PowerShell 中）：

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

然后，你可以通过 uv 命令访问它。安装 uv 不会破坏你现有的任何 Python 安装——它是独立工具，所以即便只是想试试，安装它也很安全。

为项目管理 Python 版本

对于任何 Python 项目来说，使用虚拟环境始终是个好习惯。它能把不同的代码片段和依赖互相隔离，而且以我的经验来看，尽早养成使用虚拟环境的习惯可以省去很多麻烦。

uv 天然使用虚拟环境，所以一旦开始使用 uv，上手虚拟环境就非常容易了。uv 会根据工作目录（或上级目录）中的 pyproject.toml 文件中指定的内容，为你构建一个 Python 环境。pyproject.toml 是声明 Python 项目依赖的现代标准格式。一个最基本的 pyproject.toml 可能长这样：

toml
[project]
name = "my_project"
version = "1.0.0"
requires-python = ">=3.9,<3.13"
dependencies = [
"astropy>=5.0.0",
"pandas>=1.0.0,<2.0",
]

本质上，它只需要指定要使用的 Python 版本和若干依赖。添加名称和版本号也是不错的选择。（温馨提示：对于作为包发布的项目，比如发布到 pip 和 uv 使用的 Python Package Index（PyPI），pyproject.toml 是声明发布包所需一切信息的现代方式。）

用 uv 创建新项目

用 uv 开始一个全新的 Python 项目，可以运行：

bash
uv init

这将为你创建一个新项目，包含 pyproject.toml、README.md 以及其他必要的样板文件。这个命令有很多不同的运行方式，比如 uv init --bare（只创建 pyproject.toml）、uv init --package（搭建新的 Python 包）等等。建议运行 uv init --help 来查看它们的详细说明。

已有或创建 pyproject.toml 之后

一旦你初始化了一个项目——或者如果项目里已经有 pyproject.toml 文件——使用 uv 就非常容易了。你只需要在 pyproject.toml 文件所在的目录中执行 uv sync。

这个命令（事实上，如果你之前还没运行过 uv，大多数 uv 命令都会这么做）将会：

1. 自动安装一个有效版本的 Python（如果你本地还没有的话）
2. 把所有依赖安装到目录下 .venv 这个新的虚拟环境中
3. 在目录中创建一个 uv.lock 文件，该文件保存了每个已安装包的精确、跨平台的版本信息——这样一来，你的同事就能精确复现你的 Python 环境。

原则上，你可以像在其他工具中那样“激活”这个新虚拟环境，但最“uv 风格”的使用方式，其实是直接用 uv run 作为任何命令的前缀。这个命令会自动为你找到正确的虚拟环境，并借它来运行你的命令。比如说，要执行某个脚本——与其写 source .venv/bin/activate 再 python myscript.py，不如直接运行：

bash
uv run myscript.py

两者效果完全一样。同理，如果需要用到某个“工具”，比如 Jupyter Lab，可以直接在项目目录下执行 uv run jupyter lab，而不必先“激活”环境，再单独运行 jupyter lab。

添加依赖

你可以直接手动编辑 pyproject.toml 文件：uv 能够检测到变更并重新构建项目的虚拟环境。但 uv 也提供了更简单的添加依赖方式——你可以直接运行 uv add numpy>=2.0 来添加包，并可以指定版本限制（如上面的例子）。此命令会自动帮你编辑 pyproject.toml。

uv add 在添加来自 Git 或本地计算机上其他位置的远程依赖时，功能也异常强大（不过这里就不深入讨论了）。

锁定 Python 版本

最后，我认为 uv 最有用的功能之一，是为项目钉住（pin）特定一个 Python 版本。运行 uv python pin 3.12.9 会为当前项目以及任何使用 uv 的人，精确钉死 Python 版本为 3.12.9——这意味着你真正可以在多台机器上复现完全相同的 Python 安装环境。

uvx：无须搭建，即刻运行工具

但有些时候，你可能只是想在某个地方快速运行一个工具——比如用 Ruff 去 lint 某处代码；或者在一个没有环境的地方启动 Jupyter notebook 服务器；又或者只是快速启动一个附带 pandas 的 IPython 会话，以便打开某个文件。

uv tool run 命令（默认简写为 uvx）让这一切变得匪夷所思地简单。运行像 uvx ruff 这样的命令，它会自动下载你想用的工具，并放入一个一次性的虚拟环境中运行。得益于 uv 强大的缓存机制，如果该工具之前已下载过，再次运行将如闪电般迅速。

这样的应用场景非常多——一个常见场景就是用 --with 参数附带依赖，快速开启一个带 pandas 的 IPython 会话，以便快速打开和查看 parquet 文件。例如：

bash
uvx --with pandas,pyarrow ipython

或者，也许只是想快速启动一个 Jupyter Lab 服务器，以便打开某个学生发给我的 Jupyter notebook：

bash
uvx --from jupyter-core jupyter lab

坦诚地说，还有太多其他的奇怪场景，只是一次性的需求，这时 uvx 的存在真的极大提升了幸福感。因为有了 uvx 这张“免死金牌”，即使一直使用虚拟环境，我也不会有任何觉得拘束或错失感。

如果这还没说服你：一段个人经历

我去年发现 uv，是在和我们其他可爱的开发者一起构建 The Astrosky Ecosystem 时（这是一个为天文学爱好者构建开源社交媒体集成的美妙项目）。由于多位开发者在不同操作系统上异步协作，管理 Python 安装很快变成了一个巨大的难题。

对我们而言，uv 是一个极为强大的简化工具，已被用于我们整个技术栈。作为开发者，我们都能使用完全一致的 Python 安装，这对我们至关重要——因为我们使用的众多半实验性依赖，每个版本都可能引入破坏性变更。在 GitHub Actions 上，我们计划用 uv 快速构建 Python 环境并运行单元测试。在生产环境中，uv 已经为我们所有服务器管理 Python。能总是确信 Python 和包安装在我们所有机器上都会以一致、正确的方式运作，这种感觉实在太棒了。

这就是为什么我认为 uv 是十年来 Python 生态系统中发生的最好的事情。

了解更多

uv 官方文档还有大量信息，包括入门页面、更深入的指南、核心概念详解以及完整的命令行参考。

原文链接：https://emily.space/posts/251023-uv