使用 uv 管理 Python 项目

简介

什么是 uv

随着 Python 开发的需求日益增加，开发者越来越依赖各种包管理工具来简化项目的包安装和依赖管理。uv 是一个由 Rust 编写的 Python 包管理工具，它的主要优势在于高效的性能和快速的包安装速度。uv 作为一个全新的工具，旨在解决传统 Python 包管理工具（如 pip 和 conda）在某些场景下的性能瓶颈，尤其是在处理大量依赖包时。

为什么用 uv

与其他 Python 中的包管理工具相比，uv 更像是一个全能选手，它的优势在于：

• 速度快：得益于Rust，uv 工具的速度让人惊艳，比如安装依赖，速度比其他工具快很多；
• 功能全面：uv 是“一站式服务”的工具，从安装 Python、管理虚拟环境，到安装和管理包，再到管理项目依赖，它统统都能处理得很好；
• 前景光明：背后有风投公司 Astral 支持，且采用了 MIT 许可，即使未来出现问题，社区也有应对的办法；

参考链接

• python uv 的官方文档
• Python包管理不再头疼：uv工具快速上手

安装 uv

如果是 macOS 或是 Linux，可以使用下面的命令进行安装：

如果是 Windows，则使用下面的命令安装：

安装成功之后，可以运行 uv help 查看是否安装成功，出现下面的提示则安装成功：

使用 uv 新建项目

这里我们展示如何在一个新项目中使用 uv。

创建项目

创建一个项目，使用uv init <project dir>命令。创建之后会在文件夹中生成一些文件：

uv 默认使用 git 进行版本的管理。uv工具主要使用的两个文件：

• pyproject.toml：定义项目的主要依赖，包括项目名称、版本、描述、支持的 Python 版本等信息。该文件是项目配置的中心，确保每个开发者在不同的机器上都可以使用相同的环境配置。
• uv.lock：记录项目的所有依赖，包括依赖的依赖，且跨平台，确保在不同环境下安装的一致性。这个文件由 uv 自动管理，不要手动编辑。

同步依赖

创建项目之后，我们同步项目依赖，使用 uv sync 命令。这个命令主要用于同步项目的依赖和配置。具体来说，它的作用是确保项目中的依赖与锁定文件（如 uv.lock）中的版本一致，解决版本不一致或缺少依赖的问题。同时运行之后会创建 .venv 文件夹，用于存储 Python 环境信息：

运行项目

用uv管理项目的话，我们就使用uv的命令来运行代码，可以不像以前那样使用python xxx.py来运行。我们可以使用 uv run 的命令来运行脚本：

添加和删除库

当你需要添加新的依赖时，可以使用 uv add 命令。例如，安装 requests 库：

如果我们想要删除库，则可以使用 uv remove 命令。

需要注意，uv会自动管理库之间的依赖，不需要我们手动修改配置文件。

特定分组的依赖

很多时候我们需要按照功能区分依赖。有的时候不需要安装所有的依赖，这个时候可以用到 optional 来进行安装。例如我们希望将 numpy 设置为额外的安装库，使用 tools 时候进行安装：

此时pyproject.toml 会多出以下的内容：

之后在安装的时候，我们可以使用下面的命令进行安装：

或是可以使用 extra 参数进行安装：

关于这部分的详细内容，可以查看链接：

• Question: What’s the difference between optional-dependencies and dependency-groups in pyproject.toml?
• uv optional-dependencies

使用 uv 管理现有的项目

这一部分我们介绍如何将现有的项目转为使用 uv 来进行管理。

初始化项目

首先我们使用 uv init 来完成项目的初始化，这里可以指定特点版本的 Python 项目。在项目目录下运行下面的命令：

此命令创建的标准项目结构包含pyproject.toml和uv.lock文件。

添加依赖-conda 迁移到 uv

导出依赖文件 requirements.txt：

使用 uv 项目作为管理：

更多内容可以参考，从Anaconda迁移至UV技术实践与解析。

常用的 uv 命令

这一部分详细内容可以参考链接，uv Features。

管理和安装 Python

• uv python install: Install Python versions.
  • 例如安装 python3.12 版本：uv python install 3.12
• uv python list: View available Python versions.

uv 管理 Python 项目

• uv init: Create a new Python project.
• uv add: Add a dependency to the project.
• uv remove: Remove a dependency from the project.
• uv sync: Sync the project's dependencies with the environment.
• uv lock: Create a lockfile for the project's dependencies.
• uv run: Run a command in the project environment.
• uv tree: View the dependency tree for the project.
• uv build: Build the project into distribution archives.
• uv publish: Publish the project to a package index.

uv 脚本

• uv run: Run a script.
• uv add --script: Add a dependency to a script
• uv remove --script: Remove a dependency from a script

总结

uv 提供了快速、简洁且高效的包管理功能，特别适用于处理大型项目和大量依赖的场景。与 pip 和 conda 相比，uv 具有显著的性能优势，尤其在包安装和更新速度方面。同时，它的简洁命令和灵活的项目管理功能也使得它易于上手。