uv 简单入门指南

前言

在学习斯坦福大学 2025 年春季的 CS336 时，第一次作业使用到了 uv，所以有了本篇记录。

uv 是一款基于 Rust 开发的高速 Python 依赖管理和项目管理工具，GitHub 仓库链接在这里。

如果想要全面地了解 uv，阅读文档是最好的方法。

• uv 官方英文文档
• uv 中文文档

安装 uv

在 Linux 或者 MacOS 的命令行中执行如下命令。

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

我使用的是 MacOS，还可以直接使用 homebrew 进行包管理，在命令行中直接执行如下命令。

brew install uv

如果使用的是 Windows，则 Powershell 中执行如下命令。

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

如果想要更新 uv，应该在命令行中执行如下命令。

uv self update

使用 uv

更换镜像源

出于中国大陆的网络问题，我们在使用 uv 进行依赖安装的时候需要进行换源，这里我使用的是设置当前 Shell 环境变量的方式，在我的 .zshrc 配置文件中添加了如下内容。

export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

或者也可以在项目的 pyproject.toml 中加入以下内容。

[[tool.uv.index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
default = true
 
[tool.uv.pip]
index-url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

Python 版本管理

学习 uv 的使用，首先学习如何使用 uv 进行 Python 版本管理。

• uv python install：安装 Python 版本。
• uv python list：查看可用的 Python 版本。
• uv python find：查找已安装的 Python 版本。
• uv python pin：为当前项目指定使用的 Python 版本。
• uv python uninstall：卸载 Python 版本。

例如，如果想要安装 3.12 版本的 Python，应该使用 uv python install 3.12。

运行 Python 文件

• uv run：运行脚本。

例如，使用 uv run main.py 来运行 main.py 这个 Python 文件。

项目管理

• uv init：创建一个新项目。
• uv add：向项目添加依赖。
• uv remove：从项目中移除依赖。
• uv sync：同步项目依赖到环境。
• uv lock：为项目依赖创建锁文件。
• uv run：在项目环境中运行命令。
• uv tree：查看项目的依赖树。
• uv build：构建项目的分发包。
• uv publish：将项目发布到包索引。

简单流程

使用 uv 创建一个项目的简单流程如下。

首先在命令行中使用 uv init 创建一个新的 Python 项目。

uv init HelloWorld
cd HelloWorld

uv 会自动创建以下文件。

• .python-version：记录这个项目需要用哪个 Python 版本。
• README.md：项目的介绍文档。
• hello.py：演示代码。
• pyproject.toml：项目配置与依赖定义文件。

使用 uv run 命令来运行 Python 文件。

uv run hello.py

环境管理

第一次运行项目命令时，uv 会在项目的根目录下创建一个虚拟环境 .venv 和 uv.lock 文件。

我以前使用 Conda 进行环境的管理，但是在 uv 中主要是使用 venv。

例如使用 uv 创建一个 Python 3.12 的环境，在命令行中执行如下操作。

uv venv --python 3.12

这样 Python 解释器会存放在当前目录的 .venv 中，可以使用 source .venv/bin/activate 命令进行激活，使用 deactivate 命令进行退出，十分方便。

依赖管理

在进行项目依赖管理的时候，使用 uv add 和 uv remove 命令来添加或者删除依赖，当然也可以使用经典的 pip 工具，只是需要加上 uv 的前缀，使用 uv 安装依赖是十分快速的。

uv pip install pandas
uv pip uninstall pandas

uv add requests
uv remove requests

如果要导出常用的 requirements.txt 文件，应该使用 freeze 命令。

uv pip freeze