UV 使用教程

安装

官方文档：https://docs.astral.sh/uv/getting-started/installation/

          bash
          
        
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" #Windows
# 或者
curl -LsSf https://astral.sh/uv/install.sh | sh  #Linux/macOS

在 window 的使用中，我非常讨厌软件安装在 C 盘，所以如果是 windows 用户别急，如果要自定义目录，那就增加变量：

          bash
          
$env:UV_INSTALL_DIR="D:\Tools\uv"; powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

注: 安装脚本默认会自动将安装目录添加到你的用户级 PATH。

当然，你也可以自己去 github 下载 uv，uvw，uvx，然后自行往 PATH 里面添加环境变量

初始化项目

          bash
          
        
# 新建项目
uv init my-project
cd my-project

# 迁移已有 Python 项目到 uv
cd my-project
uv init

初始化后一般会生成/补齐这些东西（不同版本细节可能略有差异）：

.git/、.gitignore、README.md：常规项目文件
main.py：示例入口文件，不需要就删
pyproject.toml：项目元信息 + 依赖（核心）
.python-version：固定该项目使用的 Python 版本（很建议保留）

pyproject.toml 大致长这样

          toml
          
        
[project]
name = "test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []

固定 Python 版本

编辑 <font style="background-color:rgb(228, 228, 231);">pyproject.toml 文件中的 <font style="background-color:rgb(228, 228, 231);">requires-python 字段，指定当前项目所需的 Python 版本，例如：

          toml
          
        
[project]
requires-python = ">=3.12"

然后运行以下命令安装指定版本的 Python：

bash

uv python pin 3.12

这会更新 .python-version，并让项目后续操作尽量围绕这个版本走。

创建虚拟环境

bash

uv venv

会在项目目录下创建 .venv/。

激活方式:

          bash
          
        
.venv\Scripts\activate #Windows
source .venv/bin/activate #macOS/Linux

当然只要项目目录有虚拟环境目录，也不用手动激活，只需要执行uv run main.py即可。

依赖管理

安装依赖 : uv add tqdm
查看依赖树: uv tree
卸载依赖： uv remove tqdm
环境复现：uv sync，当你在另一台机器克隆项目后，只要仓库里带着：pyproject.toml、uv.lock就可以使用
清理缓存：uv cache clear

虽然 uv 也提供了uv pip来兼容 pip 的的一些用法，但是项目依赖尽量统一用 **uv add/remove/sync** 管，否则很容易出现 pyproject.toml / uv.lock 不同步，环境复现翻车

PyTorch 安装

有些包会要求从它自己的源安装（最常见就是 PyTorch 的 CUDA 轮子）。uv 的做法是：定义一个额外索引源 + 指定哪些包从该源装。

          bash
          
        
[[tool.uv.index]]
name = "pytorch-cu130"
url = "https://download.pytorch.org/whl/cu130"
explicit = true

[tool.uv.sources]
torch = [
  { index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
torchvision = [
  { index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]

explicit = true：这个索引不会被默认用，只有你指定的包才走它
marker：限制平台

配置镜像源

需要换 PyPI 镜像源时，可以在 pyproject.toml 加：

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

当然，每次设置其实很麻烦，可以配置环境变量，UV_DEFAULT_INDEX <url>，永久生效