【工具教程】uv包管理：torch安装与docker部署

【工具教程】uv包管理：torch安装与docker部署

前两天用conda创建新环境时，发现torch的安装会有问题。使用conda install安装的torch，会在import torch的时候报错：

1
ImportError: /home/wsl/anaconda3/envs/testTorch/lib/python3.11/site-packages/torch/lib/libtorch_cpu.so: undefined symbol: iJIT_NotifyEvent

这个问题很棘手，反正最终无论如何制定渠道，只要使用conda install就会出问题，太恶心了。前一阵子就发现Pytorch官方的推荐安装途径中，conda被删除了。当时还没怎么在意，现在感觉装起来是真的恶心。我如果用pip安装的话那还啥conda，conda吹嘘的优秀科学计算管理能力用不上，那还不如不用conda，转去使用很多人的推荐的uv。

1. uv 的安装

最简单的方式就是直接在你的全局python下使用pip安装：

1
pip install uv

通过这种方式安装的uv会在全局创建一个环境变量。

还有其他的安装方式，我没试过，可以查看这个链接里的教程：安装 | uv 中文文档

2. uv创建虚拟环境

在你的项目的工作目录下使用：

1
uv venv --python 3.12

这里的3.12是指定的python版本，可以根据项目的需求进行更改。使用上述命令后，会在工作目录下自动创建一个名为.venv的虚拟环境。并且终端会输出一个激活的地址：Activate with: .venv\Scripts\activate，不激活也可以安装管理packages，也可以运行脚本。

在当前目录下使用：

1
uv init

会在当前目录下生成初始化该项目的相关文件，包含：python-version(指明python版本，可以不理他)、project.toml(项目相关的配置文件)、README.md(项目介绍文件，使用markdown语法)、main.py(可以不理他)。这里面最重要的是project.toml，在打包项目，管理依赖的时候非常有用。

3. 安装packages

不管你有没有激活虚拟环境，直接在当前的工作目录内使用uv add指令就可以自动在当前的这个虚拟环境内安装对应的包，并且会自动地维护project.toml。例如，你如果需要在你的虚拟环境内添加flask库，就输入：

1
uv add flask

就可以自动地在当前的虚拟环境下安装flask，并且会自动地在project.toml的dependencies里面添加flask以及对应的版本号。

在多人协作场景下，想要使用他人的project.toml文件来更新自己的虚拟环境，就只需要使用：

1
uv sync

uv就会自动读取project.toml中的dependencies内容，来更新你的虚拟环境。

安装完环境，如果你没激活虚拟环境，但仍然想运行代码，例如运行test.py，可以使用：

1
uv run test.py

4. 安装pytorch

直接使用uv add torch可能会自动安装cpu版本的pytorch。准确地安装cuda版本的pytorch要编辑project.toml文件。

现在pytorch的版本发页中找到对应版本的torch与cuda的pip安装指令。PyTorch历史发行版本

例如我想安装CUDA 12.4、torch 2.5.1的pytorch，对应的pip安装指令是pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 –index-url https://download.pytorch.org/whl/cu124

我就会在我的project.toml里加入以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
dependencies = [
	# 保留你先前的其他packages
    "torch==2.5.1",
    "torchvision==0.20.1",
]

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

[[tool.uv.index]]
name = "pytorch-cu124"   # 这里的名字要和上面的index对应
url = "https://download.pytorch.org/whl/cu124"  # 这里的url就是pip安装的时候最后的那个参数
explicit = true  # 加上这一行可以保证只有安装torch的时候会在上面的url里面找，不影响其他包的安装

先在dependencies里面加上torch、torchvison以及对应的版本号，torchaudio我用不上就没加上去。然后后面的[tool.uv.sources]和[[tool.uv.index]]你就照抄就行，如果要安装torchvision的话你就在[tool.uv.sources]照着多补一行。如果要安装cuda 11.8的，你就把里面的所有124改成118就行。

改写玩project.toml后，使用uv sync就会自动安装torch。

由于安装torch的时候直连pytorch官网，没有代理加速的话下载比较慢，所以在使用uv sync之前可能需要手动设置一下代理地址。以clash为例，clash使用的默认端口是7890，所以在安装的时候使用以下命令：

1
2
3
4
# Linux / macOS / Windows (用PowerShell，cmd可能不行)
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
uv sync

设置一个临时代理，然后下载的时候走临时代理就行。

5. Docker部署

参考在 Docker 中使用 uv | uv 中文文档

这里提供一个我自己使用过可行的Dockerfile，用于build一个深度学习相关项目的镜像，要用到pytorch，cuda。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# 使用 NVIDIA 提供的 CUDA 开发镜像（含 gcc、make 等）
FROM nvidia/cuda:12.6.3-devel-ubuntu22.04

# 设置非交互式安装
ENV DEBIAN_FRONTEND=noninteractive

# 使用5001端口
EXPOSE 5001

# 安装必要系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates

ADD https://astral.sh/uv/install.sh /uv-installer.sh

RUN sh /uv-installer.sh && rm /uv-installer.sh

ENV PATH="/root/.local/bin/:$PATH"

# 复制项目代码
COPY . /app
# 设置工作目录
WORKDIR /app
ENV UV_NO_DEV=1

# 底下这个是Windwos/MacOS使用的代理
RUN http_proxy=http://host.docker.internal:7890 \
    https_proxy=http://host.docker.internal:7890 \
    uv sync --locked

# # 这个是Linux系统使用的代理
# RUN http_proxy=http://172.17.0.1:7890 \
#     https_proxy=http://172.17.0.1:7890 \
#     uv sync --locked
    
CMD ["uv", "run", "test.py"]

使用时确保uv.lock文件没有被ignore，按照相应的规范，.venv文件要被igore。模型权重相关的文件也应该被ignore，在运行的时候通过挂载被容器访问。

参考资料

快速入门 | uv 中文文档

https://www.bilibili.com/video/BV1CbfFYFE25/

#教程
【工具教程】uv包管理：torch安装与docker部署
https://blog.sheep0.top/2025/12/12/【工具教程】uv包管理：torch安装与docker部署/
作者
Sheep0
发布于
2025年12月12日
许可协议