0. 参考文档

• 官方文档：https://docs.astral.sh/uv/
• B站视频链接：111
• B站up主笔记：https://mirage-thought-d06.notion.site/Python-24f747825dae80fdb270c15b76b61b26
• 下载GPU版本的torch：222

1.介绍

以下视频介绍为什么采用uv进行项目管理：从pip到uv：一口气梳理现代Python项目管理全流程

2.安装

步骤1 下载

1. macOS／Linux

• 用 curl 下载脚本并用 sh 执行

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

• wget下载

wget -qO- https://astral.sh/uv/install.sh | sh

• URL

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

2. Windows

• 使用 irm 下载脚本并用 IEX 执行：

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

• URL

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

步骤2 PATH配置

在安装后需要进行PATH配置。以Windows的Power’shell安装为例，会有如下输出：

PS D:\uv_test> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.9.18/install.ps1 | iex"
Downloading uv 0.9.18 (x86_64-pc-windows-msvc)                                                                     Installing to C:\Users\linkai\.local\bin                                                                           
  uv.exe                                                                                                           
  uvx.exe                                                                                                          
  uvw.exe                                                                                                          
everything's installed!

To add C:\Users\xxx\.local\bin to your PATH, either restart your shell or run:

    set Path=C:\Users\xxx\.local\bin;%Path%   (cmd)
    $env:Path = "C:\Users\xxx\.local\bin;$env:Path"   (powershell)

可以选择手动在系统环境变量的PATH添加C:\Users\xxx\.local\bin,也对应地输入以上指令。

步骤3 验证

在Powershell输入以下指令，若有对应版本，则安装成功。（若是在vscode安装的，记得将vscode关闭后，重新打开vscode和一个新的终端）

uv --version

uv 0.9.18 (0cee76417 2025-12-16)

步骤4 设置包下载源

• 若只是针对某一个包，指令和pip类似，如下所示：

uv add numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

• 若针对某个项目
  在项目的 pyproject.toml 中配置源，添加 [[tool.uv.index]] 部分。（但是我觉得应该把torch先安装了，清华源的torch下载默认是cpu版的，后续琐碎的库再用清华源？）

[[tool.uv.index]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true  # 设置为默认源

3.基础操作

3.1 创建虚拟环境

可以采用以下任意一条指令创建虚拟环境。

uv venv                     # 创建环境
uv venv my-env -p 3.11      # 指定环境名字和python版本
uv venv -p python@3.11 # 使用 python3.11 创建 .venv

指令执行后会在项目根目录下有一个虚拟环境名（默认为.venv）的文件夹。

3.2 激活环境(可选)

输入以下指令可以激活虚拟环境。但是直接运行py文件可以自动激活虚拟环境。.venv是虚拟环境名。

.venv\Scripts\activate

3.3 标准化 Python 项目

输入以下指令对项目先进行一个初始化使其符合标准。

uv init

在初始化之后会在根目录下生成以下文件：

• pyproject.toml
  最重要的文件。它定义了项目的名称、版本、以及依赖包（比如 requests, numpy 等）。以后你用 uv add 安装的包都会记录在这里。
• .python-version
  记录项目使用的 Python 版本（与虚拟环境指定py版本一致），确保所有开发者使用相同的环境。
• README.md
• .gitignore
  告诉 Git 不要上传哪些垃圾文件（比如虚拟环境文件夹 .venv 或缓存文件）。
• main.py

3.4 依赖项安装

3.4.1. 拉取别人的项目

• 步骤一：观察有没有pyproject.toml文件。如果没有该文件，先输入uv init对项目进行初始化，生成pyproject.toml文件。
• 步骤二：安装GPU版本的torch。当pyproject.toml文件没有指定torch的下载源的时候，会从默认的 PyPI 源下载（即对应版本的cpu版而不是GPU版）。因此需要在pyproject.toml文件添加以下内容。

[tool.uv.sources]
# 这个配置段用于为特定包指定专属的下载源（覆盖默认的 PyPI 源），格式为 包名 = [源规则列表]。
# 为torch指定2.9.0版本 + CUDA 12.6源（仅Linux/Windows生效）
torch = [
  { index = "pytorch-cu126", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]

[[tool.uv.index]]
# 自定义包索引源的配置段（双括号表示可定义多个索引），这里定义了名为 pytorch-cu126 的源
# 若官方cu126源无2.9.0，需替换为包含该版本的源地址（比如自定义镜像/私有源）
name = "pytorch-cu126"
url = "https://download.pytorch.org/whl/cu126"
explicit = true	# 只有在 sources 中明确指定用这个源的包，才会从这里下载；其他包仍使用默认的 PyPI 源。

• 步骤三：其他依赖。若有有pyproject.toml文件，可以直接输出以下指令，达到类似pip install -r requirements.txt的效果；

uv sync

有的项目没有pyproject.toml文件，只有requirement文件，输入以下指令进行安装，并更新pyproject.toml文件。

uv add -r requirements.txt

3.4.2. 安装单个包

在开始在之前，先说明两个概念：
（1）生产依赖：项目运行 / 部署后必须的依赖（缺了项目就报错） ，会被写pyproject.toml文件中的dependencies，例如 dependencies = [“requests>=2.31.0”]
（2）开发依赖： 仅开发 / 测试 / 打包阶段用的依赖（运行时完全不需要），会被写pyproject.toml文件中的dev。例如 dev = [“pytest>=7.0.0”]

• 安装生产依赖的包
  在执行以下指令后，会进行安装 + 写入 pyproject.toml 文件的生产依赖区。

uv add xxx

• 安装开发依赖的包
  在执行以下指令后，会进行安装 + 写入 pyproject.toml 文件的开发依赖区。

uv add --dev xxx

• 测试安装
  仅安装，不修改 pyproject.toml文件，临时安装测试，不记录依赖，若删了环境重装，这个包就丢了。

uv pip install numpy

3.5 生成requirement文件

若采用uv add安装依赖，会在根目录下生成uv.lock文件（记录子依赖的版本）。可以采用以下指令基于uv.lock文件生成requirement文件。

uv export --format requirements-txt > requirements.txt

4. 进阶操作（待补充）