Python-CUDA-CuDNN-Pytorch-Jupyter配置合集

Python CUDA CuDNN Pytorch Jupyter配置合集

本文主要内容为使用 uv 搭建隔离的 Python 环境，设置VSCode Jupyter 相关配置，安装匹配显卡的 CUDA 与 cuDNN，并配置并验证 PyTorch GPU 加速。本文拆分为四个部分：

环境与依赖管理（uv）
VSCode Jupyter 相关配置
CUDA / cuDNN 组件
PyTorch 安装、验证与优化

一：uv 环境与依赖管理

1. 了解 uv

uv 是用 Rust 编写的超快 Python 包与环境管理工具，集成：

Python 版本安装 (多版本共存)
虚拟环境管理
依赖解析与锁定
pip + pip-tools + virtualenv 的组合替代

项目地址：https://github.com/astral-sh/uv

官方教程：https://uv.doczh.com/

uv（以及 virtualenv、venv 等工具）的核心工作原则：隔离。

uv 管理的 Python：干净的“模板库”

当您使用 uv tool install python 安装了多个 Python 版本（例如 3.9, 3.10, 3.11）后，uv 会将这些版本作为干净的、原始的模板存储在自己的目录中（例如在 ~/.uv/toolchains/ 下）。

这些解释器是“纯净版”的，只包含 Python 标准库和基础的 pip、setuptools 等。

创建虚拟环境：复制模板，而非链接

当运行 uv venv --python 3.11 时，uv 会执行以下操作：

在自己的“模板库”里找到 Python 3.11 这个干净的模板。
将模板的所有必要文件复制到您指定的目录（通常是项目下的 .venv）。
这个新创建的 .venv 目录就是一个全新的、独立的 Python 环境。

安装包：只影响虚拟环境

接下来，无论您使用 uv add requests 还是 uv sync，所有安装的第三方包（requests, numpy 等）都会被严格地、且仅被安装到当前项目的 .venv 目录下的 site-packages 文件夹中。

这个过程对 uv 存储的原始 Python 模板（~/.uv/toolchains/）没有任何影响。 它始终保持纯净，以便下次创建新的虚拟环境时，还能提供一个干净的起点。

强烈建议下方所有uv常用操作结合教程和AI弄明白细节

2. 安装 uv

Windows (PowerShell)：

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

安装完成后一般在用户本地 bin 目录，确保已加入 PATH。验证：

1	uv --version

3. 安装 / 管理 Python 版本

列出可用版本：

1	uv python list --available

安装指定版本：

1	uv python install 3.12

查看已安装：

1	uv python list

4. 初始化项目与虚拟环境

方式一（手动）：

mkdir demo-cuda && cd demo-cuda
uv init
uv venv .venv --python 3.12
# 激活虚拟环境
.venv\Scripts\activate
#进行正常使用
python xxx.py
# 关闭虚拟环境
deactivate

# 或者直接调用环境运行代码，无需激活
uv run xxx.py

使用VSCode打开虚拟环境所在的项目文件夹（必须是venv文件夹的上一级文件夹及以下），点击右上角即可识别并且选择内核

5. 配置国内镜像 (可选)

临时：(numpy 仅作示例，可替换为其它包名，mirrors.aliyun.com为阿里云，可替换其他镜像源)

1	uv pip install -i https://mirrors.aliyun.com/pypi/simple numpy

全局：

1	uv config set index-url https://mirrors.aliyun.com/pypi/simple

6. 使用 uv 统一管理包

增加或者删除 pyproject.toml中的依赖：
具体格式参见：依赖声明格式文档

通过 pyproject.toml和uv.lock同步所有环境依赖：

在正常情况下，uv sync 根据的是 uv.lock 文件。只有在 uv.lock 文件不存在或你使用了 --upgrade 参数时，它才会去读取 pyproject.toml。

下面把 uv 的 add / remove / lock / sync 的关系、自动锁与自动同步的行为，以及默认路径查找规则讲清楚，便于在 VS Code 里稳态使用。

add / remove / lock / sync / run的关系

uv add
- 修改 pyproject.toml（把依赖写入正确的依赖组，例如默认或开发依赖）。
- 解析依赖并更新 uv.lock。
- 安装到项目虚拟环境（相当于“锁 + 同步”一次性完成）。
uv remove
- 从 pyproject.toml 移除依赖。
- 解析并更新 uv.lock。
- 同步虚拟环境（卸载/回滚到匹配锁文件的状态）。
uv lock
- 只做解析与写入 uv.lock，不改变当前虚拟环境，仅更新锁文件。
- 若pyproject.toml需求版本为>=1.0,最新包为1.1，则不会更新，仍然认为满足要求，除非修改为>=1.1
uv sync
- 让当前虚拟环境与锁文件一致。若 uv.lock 不存在，会先解析并生成 uv.lock，然后再安装。
- 使用了 --upgrade 参数时，会去读取 pyproject.toml，直接覆盖生成一份新的uv.lock
uv run
- 使用当前虚拟环境运行代码，无需activate和deactivate

自动锁与自动同步的“坑”与建议

自动解析触发点
- 执行 add/remove 会自动解析并更新锁文件，随后同步环境。
- 执行 sync 时若锁文件缺失或过期，也会自动解析并写锁。
手工编辑 pyproject.toml
- 不通过add或者remove，直接改版本约束后，下一次 sync 可能需要手动重写锁文件，需要手动uv lock；
- 先更新锁而不动环境，用 uv lock；若想更新安装，再用 uv sync。

7. 手动安装包（pip 兼容支持，建议使用uv add和remove）

安装/卸载包(以numpy作为例子)：

1 2	uv pip install numpy uv pip uninstall numpy

升级包：

1	uv pip install --upgrade numpy

8. uv本体相关

升级 uv 本体：

1	uv self update

清理下载缓存（减少磁盘占用）：

1	uv cache prune

如果想要在任意目录使用，此时寻找上级虚拟环境不存在，要使用uv虚拟环境的python：

声明全局uv run默认使用的--python参数，创建环境变量UV_PYTHON

将值改为想要设置的默认版本对应的python.exe路径即可。

之后在随意路径使用uv run xxx.py即可运行任意py代码

二：VSCode Jupyter 相关配置

什么是 Jupyter

Jupyter Notebook 是交互式计算文档格式（.ipynb），将可执行代码、可视化输出与 Markdown 混合，底层通过 Kernel（内核）执行。
Python 场景中最常用的内核由 ipykernel 提供；不同虚拟环境需分别安装自己的内核，VSCode 通过内核规范 (Jupyter kernelspec) 发现并选择。
对比形式：

.ipynb：富文本，便于探索与演示，不利于精细代码审阅 / Git diff
.py（percent / Jupytext 兼容格式）：纯文本，利于版本控制，可在需要时同步生成 .ipynb

安装

安装扩展
- 必装：Python、Jupyter
选择解释器 / 虚拟环境
- 打开包含 .venv 的项目根目录
安装内核（确保在 .venv目录执行）
1
uv add ipykernel
完成以上后，即可在 VSCode 中使用该 uv 创建的隔离环境稳定运行 / 调试 Jupyter Notebook。

三：CUDA 与 cuDNN 组件

基础概念与区别

CUDA（Compute Unified Device Architecture）是 NVIDIA 为其 GPU 提供的通用计算平台与并行编程模型；实际落地包含三层：

显卡驱动（Driver）: 随操作系统加载，向上提供统一接口。升级驱动即可提升对更新 CUDA Runtime 的兼容，无需每次安装整套 Toolkit。
CUDA Runtime / 库: 程序运行所需的核心动态库（cudart、cublas、cufft 等）。
CUDA Toolkit: 面向开发者的完整工具集合（nvcc 编译器、Nsight、头文件、静态/动态库、示例）。

cuDNN（CUDA Deep Neural Network Library）是专为深度学习常见算子（卷积 / 池化 / RNN / 归一化等）提供的高性能实现库，PyTorch / TensorFlow 等框架在底层调用它以获得更优性能与新硬件特性（Tensor Cores、FP8 等）。

1. 检查本机 GPU 与驱动

1	nvidia-smi

关注显示的 CUDA Version，其代表当前驱动支持的最高 CUDA Runtime 主版本（不等同于已安装的 Toolkit 版本）。

2. 安装 CUDA Toolkit

说明：CUDA 10/11 时代安装包组件较多；如果不是维护旧项目且硬件较新，优先使用最新版显卡驱动 + CUDA 12.x（或 PyTorch 官方适配的推荐版本）。

选择版本：https://developer.nvidia.com/cuda-toolkit-archive （与目标 PyTorch 支持矩阵匹配）

按照图形界面选择合适的 Local 版本即可，下载后点击 exe 跟随引导安装。

选择临时解压路径（安装器自动清理，可改可不改）：

如果只安装一个 CUDA 版本，且对显卡驱动没特殊要求，可选择“精简安装”（一般不推荐，易遗漏组件）。

若不想覆盖当前显卡驱动：选择“自定义”，取消勾选驱动组件。

需要多个 CUDA 版本并存：使用自定义安装 + 手动配置环境变量。

务必记录安装路径，后续需要配置系统环境变量。

如果选择自定义安装路径，配置环境变量：

在计算机上点右键，打开属性->高级系统设置->环境变量

可以看到安装程序会自动创建 CUDA_PATH 与 CUDA_PATH_V12_X（示例）环境变量（后缀版本号与实际安装版本匹配）。

自定义安装手动修改环境变量：

CUDA_PATH：
变量名：CUDA_PATH
变量值：%CUDA_PATH_V12_9%（可换为实际版本号，如 %CUDA_PATH_V12_4%）

CUDA_PATH_V12_9：
变量名：CUDA_PATH_V12_9
变量值：D:\LLM\CUDA12_9 （替换为你的自定义安装路径，注意是 bin 与 libnvvp 的上一级目录）

多版本切换流程：下载新 CUDA → 新增一个 CUDA_PATH_VXX_X → 修改 CUDA_PATH 指向目标版本（修改后需重开终端 / IDE 以生效）。

PATH：

选中 PATH，点击编辑进入 PATH 内部，然后点击右侧“新建”按钮，新建两条：

%CUDA_PATH%\bin
%CUDA_PATH%\libnvvp

配置成功验证：

1	nvcc --version

输出：

3. 安装 cuDNN

下载：https://developer.download.nvidia.cn/compute/cudnn/redist/cudnn/windows-x86_64/

选择对应CUDA的支持版本（后缀为cuda11或者cuda12，按照大版本命名）
解压并复制 include 与 lib 目录内容到 CUDA 主目录（可覆盖）
Linux 用户可直接解压到 /usr/local/cuda/ 并确认权限

在 Python 中：

1 2	import torch print(torch.backends.cudnn.version())

四：PyTorch 安装、验证

1. 安装 PyTorch（示例 CUDA 12.9）

官方链接：Get Started PyTorch

使用uv pip直接安装：（cu129可修改为具体版本）

这种方法缺点是uv sync由于 pyproject.toml和uv.lock内没有同步，会导致sync和lock出现不同步。

1	uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu129

使用uv 的pyproject.toml(xxx可替换，py约束版本根据之前安装的自己决定)：

以cuda12.9为例

[project]
name = "xxx"
version = "0.1.0"
description = "xxx"
authors = [{name = "xxx"}]
requires-python = ">=3.12,<3.13"
dependencies = [
	...其他包...
    "torch==2.8.0+cu129",
    "torchvision==0.23.0+cu129",
    ...其他包...
]
[tool.uv.sources]
torch = [
  { index = "torch-gpu" },
]
torchvision = [
  { index = "torch-gpu" },
]
[[tool.uv.index]]
name = "torch-gpu"
url = "https://download.pytorch.org/whl/cu129"
explicit = true

配置完后uv lock + uv sync即可。

2. 验证 GPU 可用性

import torch, time
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print("Using device:", device)
print("CUDA VERSION:", torch.version.cuda)
print("PyTorch VERSION:", torch.__version__)
if torch.cuda.is_available():
        print("GPU NAME:", torch.cuda.get_device_name(0))
        print("MULTI GPU COUNT:", torch.cuda.device_count())
        print("ARCH LIST:", torch.cuda.get_arch_list())
        print("CUDNN VERSION:", torch.backends.cudnn.version())
        print("CUDNN ENABLED:", torch.backends.cudnn.enabled)

# 简单张量计算性能测试
a = torch.randn(4096, 4096, device=device)
b = torch.randn(4096, 4096, device=device)
if device.type == "cuda":
        torch.cuda.synchronize()
t0 = time.time()
for _ in range(10):
        c = a @ b
if device.type == "cuda":
        torch.cuda.synchronize()
print("耗时:", round(time.time() - t0, 4), "秒")
print("结果张量:", c.shape, c.dtype, c.device)

# 显存占用情况
if device.type == "cuda":
        print("显存使用(MiB):", round(torch.cuda.max_memory_allocated()/1024/1024, 2))

3. 常见报错速查（扩展）

报错 / 现象	可能原因	处理建议
CUDA driver version is insufficient	驱动版本 < 轮子内置 CUDA Runtime 需求	升级 NVIDIA 驱动（无需重装 Toolkit）
torch.cuda.is_available() False	未识别 GPU / 驱动不匹配	更新驱动，确认没有用 WSL+宿主混淆
DLL load failed / libcuda.so not found	环境变量 PATH / LD_LIBRARY_PATH 缺失	重新打开终端，检查驱动安装，补变量
libcudnn_xxx.so 找不到	未安装 cuDNN 或路径缺失	按章节 3 安装，确认软链接 / 路径
Illegal memory access	访问越界 / 异步错误延迟暴露	加 `CUDA_LAUNCH_BLOCKING=1` 定位，检查自定义 kernel
OOM (out of memory)	batch 太大 / 片段显存碎片	减小 batch；使用 `torch.cuda.empty_cache()`；梯度累积
CUBLAS_STATUS_ALLOC_FAILED	驱动层内存不足	关闭占用显存的其它程序；重启 X / 服务器

软件配置-系列：