在Jupyter Notebook中检验PyTorch安装状态

一、认识Jupyter内核与虚拟环境的解耦机制

很多开发者在终端中通过Conda或venv安装完PyTorch并测试通过后，打开Jupyter Notebook却遇到了ModuleNotFoundError: No module named 'torch'。造成这种现象的根源在于：Jupyter的Web界面与实际执行代码的Python解释器（Kernel）是完全解耦的。

启动Jupyter Notebook的终端环境，并不等同于Notebook代码单元运行所在的环境。Notebook依据所选内核的配置文件（kernel.json）来调用特定路径下的Python执行程序。如果内核未指向正确的虚拟环境，Notebook就会在默认或全局环境中寻找依赖，从而引发找不到模块的假象。

二、标准检验四步法：从解释器到张量运算

检验PyTorch安装状态不应只停留在单纯的模块导入，而应按照由浅入深的步骤逐步排查。完整的检验包含四个操作环节：核查解释器物理路径、验证基础导入与版本号、探查加速后端支持，以及进行微型张量内存分配测试。

步骤一：打印当前正在执行代码的Python解释器路径

打开Jupyter Notebook并新建或载入一个Notebook，在第一个代码单元中运行以下代码：

import sys
print("当前运行的 Python 解释器路径：")
print(sys.executable)

判断依据：输出的完整路径中必须包含你预先创建的虚拟环境名称（例如这里的pytorch-env）。如果输出的是系统默认Python路径（如/usr/bin/python3）或基础环境（如/base/bin/python），说明内核选定有误，后续任何步骤都可能读到错误的环境。

步骤二：导入PyTorch并输出构建版本信息

确认解释器路径无误后，紧接着验证PyTorch核心模块的导入并检查版本号：

import torch
print("PyTorch 版本号：", torch.__version__)

说明：版本号末尾的后缀直接反映了PyTorch编译时绑定的计算库。以+cu118或+cu121结尾表示安装的是支持CUDA 11.8或12.1的GPU版本；若仅显示纯版本号或带有+cpu后缀，则代表这是一个CPU专属编译包，无法调用Nvidia GPU执行加速。

步骤三：检测硬件加速后端（CUDA与MPS）可用性

根据宿主机的硬件平台（Nvidia GPU服务器/工作站，或Apple Silicon芯片的Mac电脑），选择对应的加速通道检测代码：

# 1. 检测 Nvidia CUDA 支持
cuda_available = torch.cuda.is_available()
print("CUDA 加速是否可用：", cuda_available)

if cuda_available:
    print("可用 GPU 数量：", torch.cuda.device_count())
    print("当前默认 GPU 设备索引：", torch.cuda.current_device())
    print("设备型号：", torch.cuda.get_device_name(0))

# 2. 检测 Apple Silicon MPS 支持 (macOS 平台)
mps_available = hasattr(torch.backends, "mps") and torch.backends.mps.is_available()
print("Apple MPS 加速是否可用：", mps_available)

注意：如果你的计算机配备了Nvidia独立显卡，但torch.cuda.is_available()返回了False，请不要急于怀疑硬件损坏，绝大多数情况下是驱动版本与PyTorch安装的CUDA构建版本不匹配，或安装时误下载了CPU版本的轮子（Wheel）。

步骤四：分配张量并执行微型计算实测

有时底层动态链接库缺失只在真正调用计算核函数时才暴露。因此，最后一步是在目标设备上分配一个微型张量并完成简单计算：

# 自动选定最佳计算设备
if torch.cuda.is_available():
    device = torch.device("cuda")
elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
    device = torch.device("mps")
else:
    device = torch.device("cpu")

print(f"当前测试采用的设备：{device}")

# 在选定设备上初始化张量并执行运算
x = torch.tensor([[1.0, 2.0], [3.0, 4.0]], device=device)
y = torch.tensor([[5.0, 6.0], [7.0, 8.0]], device=device)
z = torch.matmul(x, y)

print("张量运算结果：")
print(z)
print("计算所在设备：", z.device)

当屏幕上能够正常输出计算结果，并且明确标注设备归属于cuda:0（或mps:0、cpu）时，证明PyTorch的核心计算引擎、内存分配器以及后端驱动在当前Jupyter Notebook内已处于完整就绪状态。

三、常见检验异常诊断与分支对比

检验过程中读者最常遇到的问题通常集中在两处：一是模块未找到错误，二是硬件加速不可用。以下针对典型现象进行具体归因与处理：

1. 辨析：“终端里安装成功了，Jupyter中却提示ModuleNotFoundError”

这个现象初看令人困惑，很多读者会认为是安装没有完成。其成立的条件通常是：你在终端激活了虚拟环境（例如conda activate pytorch-env），并执行了pip install torch；但你启动Jupyter时是在base环境中执行的jupyter notebook，且未将该虚拟环境注册为独立内核。

修正方法：不必重复安装PyTorch，只需要在对应的虚拟环境中安装ipykernel并将环境注册进Jupyter列表中（下文第四节提供具体命令）。注册后刷新页面，在Notebook顶部菜单栏中选择对应的内核即可立即解决。

2. 辨析：“只要安装了GPU，torch.cuda.is_available()就一定会是True”

很多读者认为只要计算机主板上插着Nvidia独立显卡，PyTorch就会自动启用GPU运算。实际上，该函数返回True需要同时满足以下三个硬性条件：

• 系统驱动就绪：已安装匹配该显卡芯片的Nvidia官方Display Driver，且驱动支持的最高CUDA版本不低于PyTorch所要求的版本；
• 安装包类型正确：下载的PyTorch Wheel包本身内嵌了CUDA运行时（即版本号带+cuXXX），而非默认的CPU Wheel；
• 架构支持：显卡的计算能力（Compute Capability）仍处于当前PyTorch版本的支持列表中（如过旧的Kepler架构已被新版放弃）。

四、修复内核脱节与环境注册的关键操作

如果检验步骤一发现解释器并非目标环境，可以通过以下标准操作将目标虚拟环境正式注册到Jupyter的内核列表中。

1. 在目标虚拟环境中安装 ipykernel

打开系统终端，首先激活你的目标虚拟环境（以Conda环境名为pytorch-env为例）：

# 激活虚拟环境
conda activate pytorch-env

# 安装内核桥接组件
conda install ipykernel -y
# 或使用 pip: pip install ipykernel

2. 注册内核规范（Kernel Spec）

在同一终端环境中执行内核注册指令。--name代表环境在系统内部的标识，--display-name代表在Jupyter页面下拉菜单中向你展示的名称：

python -m ipykernel install --user --name pytorch-env --display-name "Python (pytorch-env)"

3. 在Jupyter界面中完成切换

回到浏览器中的Jupyter Notebook页面，刷新标签页。点击页面顶部菜单栏的 Kernel → Change Kernel，在弹出的列表中点击刚刚创建的 Python (pytorch-env)。切换完成后，再次运行步骤一与步骤二的测试代码，即可确认内核已正确挂接。

五、总结与日常排查备忘

在日常开发与实验中，环境变化或依赖更新经常会影响Notebook的执行稳定性。掌握完整的检验闭环能够帮助我们在建模前快速确认算力底座的可靠性。

通过这套层层递进的检验流程，开发者可以在几分钟内确定问题究竟发生在“前端内核配置”、“包编译类型”还是“底层硬件驱动”，从而有的放矢地完成修复，保障后续深度学习项目的顺畅开展。