UV使用

1. 初始化

直接在项目目录里初始化，让每个项目都有自己的环境。

uv init

2. 指定 Python 版本

查看可用的 Python 版本

uv python list

安装指定 Python 版本

uv python install 3.12

为项目指定版本

uv python pin 3.12
uv init

添加依赖

uv add flask

移除依赖

uv remove flask

查看项目的依赖树

uv tree

3. pytorch-gpu 安装

PyTorch 在不同平台上的包分发规则不一样，可以按平台配置不同的 torch 版本：Windows 安装 CPU 版本，Linux 安装 CUDA 11.4 版本。

[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 就是干这个的。

uv venv

这个命令会在当前目录下创建名为 .venv 的文件夹（社区常用的虚拟环境名称），并在里面准备一个新的 Python 环境。

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

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

• 指定虚拟环境的名称或路径： 可以在命令后面加路径，指定虚拟环境的创建位置和名称。这样既能把环境放到项目外，也能给环境起一个自定义名字。

# 在当前目录下创建一个名为 my-project-env 的虚拟环境
uv venv my-project-env

# 在指定的路径下创建一个虚拟环境 (例如，在用户主目录下的 .venvs 文件夹中)
uv venv ~/.venvs/another-env

• 指定 Python 版本： 如果系统里装了多个 Python 版本，并且想给虚拟环境指定版本（比如 Python 3.9），可以使用 --python 选项。uv 会在系统环境中查找符合要求的 Python 解释器来创建环境。

# 使用系统中的 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 服务器：

$ uv run --with jupyter jupyter lab

默认情况下，jupyter lab 会启动在 http://localhost:8888/lab 。

8. 运行脚本

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

uv run xxx

uv run 的执行逻辑是：1. 检查当前目录中是否存在 .venv 目录，若不存在则创建新环境；2. 验证环境是否包含脚本所需依赖，缺失时自动安装；3. 在当前虚拟环境中执行命令，避免和其他环境混在一起。

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

参考：

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

uv — Using uv with PyTorch