在 Jupyter Notebook、VS Code、PyCharm 之间切换调试代码，碰到 NameError: name '_C' is not defined，大多是 Notebook 和 IDE 在用两套完全不一样的 Python 环境，其中一个环境里的 PyTorch、自定义 C++/CUDA 扩展包没有正确编译或者没有安装，内核解释器没有对齐，导入时底层 C 扩展模块加载失败，对外抛出这个报错。很多人习惯在 IDE 的虚拟环境 pip 安装 torch、编译自定义算子，但是 Jupyter Notebook 选了系统默认内核、别的 conda 环境，两边 torch 版本、编译出来的 _C 扩展对不上；也有一类情况是本地算子用 setuptools / torch.utils.cpp_extension 编译失败、缓存损坏、torch 版本升级之后旧的 .so/.pyd 二进制文件失效，哪怕解释器是同一个，也会找不到 _C。整套排查流程是先分别在 Notebook 和 IDE 里打印解释器路径、torch 版本，确认二者一致；再检查自定义扩展是否编译成功，清理旧编译缓存，重新编译算子，最后把 Notebook 的内核切换到和 IDE 相同的虚拟环境；把两边环境对齐之后，就能解决找不到 _C 的问题。下面区分报错来源、核对命令、排查步骤、修复方案分开说明。
一、两类常见触发来源
- 场景 1：自定义算子的 _C（最常见）
- 场景 2：PyTorch 内部底层 _C
使用 cpp_extension 编译的 CUDA/C++ 算子，编译脚本会生成一个叫 _C 的扩展模块，如果编译失败、文件丢失、版本不匹配，import 时报 _C 未定义。很多目标检测、分割仓库（Detectron2、MMDetection、yolov 系列自定义算子）都用这个名字。
极少数情况是 torch 本身安装损坏，包文件缺失，torch 的底层 C 核心模块加载失败；这类一般伴随大量其他导入异常。
二、环境对齐核对命令对照表
| 执行位置 | 代码 | 作用 |
|---|---|---|
| IDE 终端 / 脚本 | ```python |
import sys, torch
print(sys.executable)
print(torch.version)
|Jupyter Notebook Cell|python
import sys, torch
print(sys.executable)
print(torch.__version__)
|核对 Notebook 内核是不是和 IDE 一致|
|查看当前 Jupyter 可用内核|`jupyter kernelspec list`|列出所有注册内核，找到对应虚拟环境|
|安装 ipykernel（环境注册）|`python -m ipykernel install --name=myenv --display-name="myenv"`|把当前虚拟环境注册成 Notebook 内核|
三、完整排查与修复实操步骤
1. 分别在 IDE 和 Notebook 运行上面的解释器打印代码，如果路径不一样，就是环境割裂，优先处理内核。
2. 如果路径不一致：进入 IDE 对应的虚拟环境，执行 ipykernel 注册命令，之后在 Notebook 切换到这个新注册的内核。
3. 如果解释器路径已经一致，报错依然存在，说明是算子编译产物损坏：删除 `build/`、`dist/`、`.egg-info`、生成的 `.so` / `.pyd` 文件。
4. 重新运行算子编译脚本，编译前保证环境里的 torch、CUDA、gcc 版本和编译要求匹配，编译日志重点看有没有 error。
5. 编译成功后，在同一个环境里测试 import 扩展，先在 IDE 测试通过，再去 Notebook 测试。
6. 如果怀疑 torch 本体损坏：卸载 torch，从 PyTorch 官网重新拉取和 CUDA 匹配的安装命令重装。
7. 重启 Notebook 的 kernel，清除运行缓存，重新运行导入代码。
四、高频踩坑清单
- conda 环境装好，但是没有执行 `ipykernel install`，Notebook 一直跑在 base 或者别的内核。
- 先在 A 环境编译算子，之后切换到 B 环境运行，B 环境找不到编译好的 `_C`。
- 升级 torch、升级 CUDA 之后，旧的编译产物没有清理，二进制和新版 torch ABI 不兼容。
- Windows 下编译自定义扩展缺少合适版本的 MSVC，编译静默失败，生成不了 `_C`。
- 只重启 cell，不重启 kernel，旧的坏模块缓存还留在内存，报错持续复现。
- 使用 colab / 远程服务器，本地 IDE 和远端 Notebook 环境互相混淆。
【相关FAQ】
问题1：出现 NameError: name '_C' is not defined，是不是优先对齐 Notebook 和 IDE 的 torch 安装环境？
回答1：是的，如果一边 IDE 能跑、Notebook 报错，首要排查就是两边 Python 解释器、torch 版本不一致；解释器对齐之后，再排查自定义算子编译是否成功。
问题2：Notebook 和 IDE 的 sys.executable 路径一模一样，还报找不到 _C，该怎么办？
回答2：路径一致代表内核没问题，这时大多是自定义 C++/CUDA 扩展编译产物损坏，清理 build 缓存，在当前环境下重新编译算子；也有可能是 torch 安装包损坏。
问题3：仓库里的 `_C` 是什么，是 PyTorch 自带模块吗？
回答3：绝大多数开源项目里的 `_C` 是项目自己用 cpp_extension 编译出来的自定义算子模块，不是 torch 内置；PyTorch 底层内部模块一般不会直接让用户代码引用 `_C`。
问题4：已经注册 ipykernel，但是 Notebook 列表里看不到新内核？
回答4：确认执行 `ipykernel install` 的时候，激活的就是目标虚拟环境；安装完成之后刷新内核列表，必要时重启 jupyter server，而不是仅仅重启 cell。
【参考资料】
[2026-11-09]（NameError name '_C' is not defined 自定义算子编译问题）PyTorch 论坛
[2026-10-28]（jupyter ipykernel 注册，统一内核与本地虚拟环境）Jupyter 官方文档
[2026-09-16]（torch.utils.cpp_extension 编译缓存清理、ABI 版本匹配）掘金
[2026-08-04]（Detectron2 / MMDetection _C 扩展导入失败常见原因）知乎
[2026-07-12]（PyTorch C++ 扩展编译失败排查指南）towardsdatascience
【免责声明】
本文针对 `_C` 未定义报错提供环境对齐与编译排查思路；自定义算子编译依赖 CUDA、编译器、系统平台、torch ABI，不同环境编译结果存在差异；版本对齐后依然需要根据对应仓库编译文档调整参数，本文不保证编译后的算子可以正常运行。