UV使用

Posted on Edited on In
这篇笔记整理了UV的使用方法，主要包括初始化、指定python版本、添加依赖、移除依赖等。

UV使用

1.初始化

可以直接到项目所在文件夹下进行初始化，保证不同的项目下不同的环境。

1
uv init

2.指定python版本

查看可用的 Python 版本
1
uv python list
安装指定 Python 版本
1
uv python install 3.12
创建项目指定版本
1
2
uv python pin 3.12
uv init
添加依赖
1
uv add flask
移除依赖
1
uv remove flask
查看项目的依赖树
1
uv tree

3.pytoch-gpu安装

pytorch 不同的平台不同的分发规则，可以配置安装不同的 torch 版本，windows 版本安装 cpu 版本的 torch，linux 版本安装 cuda 11.4 版本的 torch。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.12.0"
dependencies = [
  "torch>=2.6.0",
]

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
  { index = "pytorch-cu124", marker = "sys_platform == 'linux'" },
]

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://mirror.sjtu.edu.cn/pytorch-wheels/cu124"
explicit = true

4.uv lock

确定一个可复现的、满足项目需求的完整依赖树，并将这个确定的状态“锁定”下来，记录应该安装什么。

5.uv sync

实际安装/更新/卸载包以匹配记录的状态。

6.创建虚拟环境：uv venv

在开始安装包之前，通常需要创建一个独立的 Python 环境，以避免项目之间的依赖冲突。uv venv 命令用于此目的。

1
uv venv

这个命令会在当前目录下创建一个名为 .venv 的文件夹（这是社区推荐的虚拟环境名称），并在其中设置一个新的 Python 环境。

详细解释： uv venv 会查找系统中可用的 Python 解释器，并复制或创建指向必要文件的链接，构建一个隔离的环境。在这个环境中安装的包不会影响到系统全局或其他项目的 Python 环境。与 python -m venv 相比，uv venv 通常快很多，尤其是在创建大量虚拟环境时。

除了在当前目录创建默认的 .venv 环境外，uv venv 还提供了更灵活的选项：

  • 指定虚拟环境的名称或路径： 你可以在命令后面加上一个路径，来指定虚拟环境的创建位置和名称。这允许你在项目的不同位置创建环境，或者给环境一个自定义的名字。
1
2
3
4
5
# 在当前目录下创建一个名为 my-project-env 的虚拟环境
uv venv my-project-env

# 在指定的路径下创建一个虚拟环境 (例如，在用户主目录下的 .venvs 文件夹中)
uv venv ~/.venvs/another-env
  • 指定 Python 版本： 如果你的系统中安装了多个 Python 版本，并且你希望为这个虚拟环境指定一个特定的 Python 版本（例如 Python 3.9），你可以使用 --python 选项。uv 会在你的系统环境中查找符合指定版本要求的 Python 解释器来创建环境。
1
2
3
4
5
# 使用系统中的 Python 3.9 创建虚拟环境 (uv 会尝试查找 python3.9, python3 等)
uv venv --python 3.9 .venv

# 同时指定环境名称和 Python 版本
uv venv my-env --python 3.10

uv 在查找 Python 解释器时非常智能，你可以指定主版本号 (3.9)，也可以指定次版本号 (3.9.10)，甚至可以使用可执行文件的名称 (python3.9)。

激活环境： 创建环境后，你需要激活它才能使用其中安装的包。激活环境的方式取决于你使用的 shell：

  • Bash/Zsh: source .venv/bin/activate
  • Fish: source .venv/bin/activate.fish
  • Nushell: source .venv/bin/activate.nu
  • PowerShell: . .venv\Scripts\Activate.ps1
  • Cmd: .venv\Scripts\activate.bat

激活环境后，你的终端提示符前通常会显示环境的名称（如 (.venv)），并且此时运行 python 或 pip 等命令时，使用的是虚拟环境中的版本。

7.Jupyter

如果正在项目中工作，则可以通过以下方式启动可以访问项目虚拟环境的 Jupyter 服务器：

1
$ uv run --with jupyter jupyter lab

默认情况下， jupyter lab 将启动服务器 http://localhost:8888/lab 。

8. 运行脚本

uv中执行脚本的启动命令为：

1
uv run xxx

uv run 的执行逻辑为： 1. 检查当前目录中是否存在 .venv目录，若不存在则创建新环境 2. 验证环境是否包含脚本所需依赖，如果缺失依赖则自动安装 3. 在当前的虚拟环境中执行命令，不会与其他环境产生冲突

以下是uv启动命令与常规Python启动命令的对比：

执行命令 环境处理
uv run xxx 自动关联虚拟环境： - 优先使用当前目录下的 .venv - 若不存在会自动创建 - 无需手动激活/停用
python xxx.py 依赖当前Shell环境： - 需手动激活虚拟环境

参考：

Python 包管理工具 uv 使用教程 - 知乎

uv — Using uv with PyTorch