我有一个运行了好几年的 Django 项目，之前一直在使用默认的 pip 管理和安装依赖，最近切换到了 uv，感觉还不错，在这儿记录一下。

什么是 uv

根据官网的介绍，uv 是一个 Python 包以及项目管理器，非常快，使用 Rust 开发。

安装和管理依赖只是它的功能之一，除此之外，它还可以创建虚拟环境，即可以取代 pip + virtualenv 的功能。

我测试了一下，uv 确实比 pip 快了很多。在使用相同的镜像源，且都是纯净的 docker 环境下，使用 pip 安装项目的依赖花了约 88 秒，但使用 uv 只用了 13 秒。

不过，安装依赖并不是一个高频操作，多花一点时间一般不是什么痛点，uv 更吸引人的是它简化了很多工作，比如内置了 Python 多版本安装以及虚拟环境管理，且能保证环境的可复现性，这就让 Python 项目的开发和发布工作简单了很多。

uv 的安装和初始化

在 macOS 或 Linux 上，可以使用以下命令安装 uv：

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

Windows 上的命令如下：

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

安装完成之后，可以使用以下命令初始化一个新项目：

uv init my-project

如果你的项目已经存在，也可以直接进入项目根目录，执行以下命令：

uv init

如果项目中已经有 requirements.txt，想改用 uv 进行管理，可以在项目根目录执行以下命令：

uv pip install -r requirements.txt

也可以直接执行：

uv sync

初始化后，uv 会在项目根目录下生成一个 pyproject.toml 文件，其中包含了项目的基本信息以及依赖项。

可以运行以下命令，锁定依赖项：

uv lock

这个命令将会在项目根目录下生成 uv.lock 文件，类似 Node.js 的 package-lock.json，其中包含了项目依赖的各个第三方库以及版本号，确保下次安装时安装的包相同。

虚拟环境

Python 默认是安装在系统中的，使用 pip 安装依赖时，默认也会全局安装，在很多情况下，尤其是需要维护多个项目时，这显然不是我们期望的，此时可以使用虚拟环境。

在 uv 中使用虚拟环境很简单。

首先，可以使用 uv 安装多个不同版本的 Python：

uv python install 3.10 3.11 3.12

然后，可以通过类似下面的命令安装虚拟环境：

uv venv --python 3.12.0

可以直接在项目根目录下执行这个命令，执行成功之后，项目根目录下会生成一个 .venv 文件夹，包含这个环境的所有信息，之后安装的包也会保存在这个文件夹下，记得将这个文件夹添加到 .gitignore 中。

如果你熟悉 Node.js，会发现这个 .venv 文件夹和 Node.js 的 node_modules 文件夹功能类似，且它更进一步，不仅包含依赖，还能包含当前项目所需的 Python 本身。

使用以下命令可以用虚拟环境中的 Python 执行指定脚本：

uv run example.py

如果你在终端中访问项目，可以使用以下命令激活当前 Python 虚拟环境：

source .venv/bin/activate

激活虚拟环境之后，可以直接用类似 python example.py 的方式来运行项目中的脚本。

使用现代 IDE（比如 PyCharm、VSCode 等）打开这个项目时，IDE 一般都能自动识别项目中的 .venv 虚拟环境。

安装依赖

配置好环境后，就可以使用类似下面的命令安装依赖了：

uv add django

这信命令会下载对应的包并安装在 .venv中，安装成功之后，会修改 pyproject.toml 和 uv.lock 文件。

如果你刚将代码从仓库中拉到本地，项目中已经有了 pyproject.toml 和 uv.lock，那么只需执行以下命令即可安装所有依赖：

uv sync

注意，这个命令会根据 pyproject.toml 解析和下载依赖，有可能会改进 uv.lock。如果是在生产环境，你希望严格按照 uv.lock 中的版本安装依赖，可以使用以下命令：

uv sync --frozen

在 docker 中使用 uv

如果你的项目需要使用 docker 发布，还有一些额外需要注意的事项。

如果你的服务器在国内，那么可能需要使用国内 pypi 镜像，uv 中要指定镜像很简单，设置相应的环境变量即可，例如下面设置使用了阿里云的镜像：

ENV UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
ENV UV_TRUSTED_HOST=mirrors.aliyun.com

在 docker 中安装依赖时，大体上有两种方式，一种是使用 uv sync 命令，如下所示：

WORKDIR /code/
COPY pyproject.toml uv.lock /code/

# 安装依赖
RUN uv sync --frozen --no-dev

ENV PATH="/code/.venv/bin:$PATH"

这种方式会在当前目录下创建虚拟环境，所有依赖都将安装到 .venv 目录下，因此需要将对应的目录加入 PATH。这种方式安装的依赖将严格遵守 uv.lock 中的版本限制，最为可靠。

或者，也可以选择将依赖直接安装到系统环境中：

RUN uv pip install --no-cache-dir --system .

注意那个 --system 参数，这种方式会将各依赖包安装到全局目录，如果你的 docker 中只有这一个 Python 项目，且不想使用虚拟环境，也可以使用这种方式安装。不过，这种方式安装时虽然也会参考 uv.lock，但并不保证各依赖的版本和 uv.lock 中严格相同。

小结

Python 发布迄今已有三十余年，一开始并没有第三方包的安装和管理工具，这和 Node.js 一发布就自带 npm 不同。如果你使用 Python 的时间较早，可能还会记得曾经有一个叫 easy_install 的工具用于安装 Python 的第三方包。

约 2008 年，pip 发布，随后在 2014 年被 Python 官方集成到 3.4 版中（以及 2.7.9 中），Python 这才有了一个官方的依赖管理工具。不过 pip 并不完美，主要是依赖解析能力较弱，无法保证每次安装后的环境完全相同，同时安装速度也有一些慢，因此后续又出现了一些新的依赖管理工具，比如 poetry、uv 等。

目前，开发 Python 项目的最佳实践是为每个项目创建独立的虚拟环境，将项目所需的依赖安装在该环境中，并通过依赖管理文件记录依赖，以确保隔离、可复现和可移植性。这些工作都可以使用 uv 完成，如果你正在开发或维护一个 Python 项目，不妨试试 uv。