【Python】uv包管理器常用命令

背景

在日常工作中，不同项目之间所使用的Python版本往往是不同的，所依赖的包版本也是不同的，如果在同一个环境中安装多个版本的包，可能会出现依赖冲突。

为了在多个项目之间管理依赖版本，出现了很多依赖管理工具，如conda、venv、uv等。这些依赖管理工具可以在不同项目间隔离依赖包，不会产生依赖冲突。

本文目的是介绍uv，uv是一个快速的Python包和项目管理器，可以创建多个相互隔离的Python环境。uv以项目为核心，每个项目下会创建一个文件夹.venv，用于存放对应版本的依赖包，达到隔离不同环境下的依赖包的效果。相比于conda，uv的安装和配置更加简单和轻量，速度较快。

除了包管理器功能，uv也支持项目管理，如创建虚拟环境、安装依赖包、运行代码、代码格式化、项目同步等。

安装

使用uv包管理器前需要安装，可根据系统按需安装。

Mac直接使用如下命令进行安装：

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

安装完成后，uv默认会安装在当前用户的~/.local/bin目录下。大多数现代shell已经将该目录添加到了PATH中，但如果没有，需要手动添加：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows使用如下命令进行安装：

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

安装完成后可以使用uv --version命令查看是否安装成功，若显示安装的版本信息，则安装成功。

使用

uv以项目为维度隔离虚拟环境，每个项目都会有一个专门的文件夹.venv用于存放依赖，将依赖包存放在项目文件夹中，而不是全局安装，原理类似于npm包管理器。

创建项目

uv本身是一个项目管理工具，当想要新建项目时，可以使用 uv init 命令创建一个项目文件夹。
如执行uv init project命令后，会创建一个project文件夹，文件夹中会包含main.py、pyproject.toml、README.md文件，用于项目初始化。

pyproject.toml 文件会记录项目的基本信息和依赖包版本，示例如下：

[project]
name = "consult"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["langchain>=1.0.2",
]

有些情况是已经创建了项目，现在想要使用uv进行环境管理，此时可以进入项目根路径直接执行 uv init 命令，该命令会在项目根路径自动创建pyproject.toml文件，初始化项目。

安装依赖

创建好项目后，需要安装依赖包，uv提供了两种方式进行依赖安装，一种是通过uv add命令进行依赖安装，另一种是使用uv pip命令进行依赖安装。

通过uv add命令进行依赖安装，uv add命令会自动将依赖包写入pyproject.toml文件中，并安装依赖包。

uv add numpy

通过uv pip命令进行依赖安装，uv pip命令类似于传统的pip命令，但速度更快。

uv pip install numpy

上面两种安装依赖的方式，都可以实现依赖安装，但推荐使用uv add命令进行依赖安装，因为uv add命令会自动将依赖包写入pyproject.toml文件中，方便后续管理。

卸载依赖

通过uv remove命令进行依赖卸载，uv remove命令会自动将依赖包从pyproject.toml文件中删除，并卸载依赖包。

uv remove numpy

执行Python命令

执行Python命令时，可以使用uv run命令，uv run命令会自动激活当前文件夹下的虚拟环境，并执行Python命令。

uv run python main.py

或者直接运行脚本：

uv run main.py

创建虚拟环境

使用过conda的同学刚使用uv时肯定有些疑惑，conda是在conda安装目录下创建虚拟环境，多个项目可以共用一个虚拟环境，但uv是在项目文件夹下创建虚拟环境，每个项目可以有自己独立的虚拟环境。

其实可以通过uv venv命令创建虚拟环境，然后使用source命令激活虚拟环境，再使用uv pip命令安装依赖包，这样就可以多个项目共用一个虚拟环境：

uv venv myenv --python=3.10
source myenv/bin/activate
uv pip install numpy

项目迁移

因为pyproject.toml文件记录了项目的基本信息和依赖包版本，所以只要有这个文件，就可以把项目所需要的依赖全部下载下来。
执行uv sync命令，uv会根据pyproject.toml文件自动下载并安装项目依赖包。

uv sync

代码格式化

uv还提供了代码格式化功能，可以格式化项目代码，使用uv format命令即可。

uv format

参考资料

• https://docs.astral.sh/uv/
• https://github.com/astral-sh/uv