Jupyter内核故障排查手记：从Kernel Error到DLL加载失败

做数据分析的人基本都碰过这个场景：代码写了一半，正打算跑个结果看看，单元格却一直卡在 "Kernel starting, please wait..."，等两分钟还是没反应；或者更干脆一点，右上角冒出一个红色的 "Kernel error"，下面跟着一长串 traceback。Jupyter Notebook 本身只是个前端界面，真正执行代码的是内核（Kernel），内核起不来、中途崩掉、或者和前端失去联系，都会表现为上面这些现象。我把本地 Windows、Linux 服务器、Docker 容器里的同类问题都排查过一遍，踩过不少坑，今天整理成一篇完整的处理笔记：覆盖最常见的 kernel error 和 kernel starting please wait，也包含比较冷门但真实存在的情况——比如网页版 Notebook 起不来、NVIM 里调用内核路径不对、代码自动补全突然失效，还有那个很经典的ImportError: DLL load failed while importing rpds。文章按"症状分类→环境排查→具体案例→预防维护"的顺序写，不管你是刚入门的小白还是被这个问题折磨过的老手，都能找到可以直接抄的解决方案。

1. 先把症状分清：kernel error 和 kernel starting please wait 不是一回事

1.1 几种报错的实际表现差异

很多人在网上搜"Jupyter kernel error"，其实搜到的内容五花八门，因为大家遇到的界面表现根本不同。我见过的大致分四类：

这里要先提醒一句：热搜词里那个 "kernel data inpage error 蓝屏" 里的 kernel 是 Windows 系统的内核，和 Jupyter Kernel 半毛钱关系都没有。那是内存分页文件读写出错导致的蓝屏，一般要检查硬盘坏道、内存条或者虚拟内存设置，别混为一谈。

1.2 动手修复前，先看这三个地方

遇到问题别急着卸载重装，先花两分钟收集信息，很多时候答案就在眼前。

第一，看启动 Jupyter 的那个终端窗口。内核进程的 stdout 和 stderr 会转发到这里，很多错误其实已经打印出来了。比如ModuleNotFoundError、SyntaxError这种，一眼就能看出问题。如果你是用桌面快捷方式或者从 IDE 里启动的，试试直接在命令行敲jupyter notebook，这样能看到完整日志。

第二，看内核选择器。菜单栏 Kernel -> Change Kernel，确认当前选的是不是你期望的那个环境。很多人电脑里装了 Python 3.9、3.11 多个版本，或者有 conda base 和虚拟环境并存，Jupyter 默认选中的内核可能根本不是你想用的那个解释器。

第三，看浏览器控制台。F12 打开开发者工具，切到 Console 和 Network 标签页，如果能看到 WebSocket 连接失败或者 403/404 错误，那问题多半出在前端和后端的连接上，跟内核本身无关。这一步很多教程不会提，但我靠它解决了至少三次"看起来像内核问题"的故障。

2. 最常见也最容易被忽略的元凶：Python 环境和内核注册表不一致

2.1 内核列表本身就是第一手诊断信息

Jupyter 之所以能在界面上选择不同环境，靠的是"内核注册表"——一堆描述文件，告诉 Jupyter"某个名字的内核应该用哪个 Python 解释器启动"。在命令行里执行这一句，你就能看到当前 Jupyter 认识哪些内核：

jupyter kernelspec list

输出类似这样：

Available kernels: python3 /home/user/.local/share/jupyter/kernels/python3 myenv /opt/conda/envs/myenv/share/jupyter/kernels/python3

看到没有，每个内核对应一个目录。Windows 上通常在%APPDATA%\jupyter\kernels下，Linux/macOS 在~/.local/share/jupyter/kernels或/usr/local/share/jupyter/kernels。目录里有个kernel.json，内容大概是：

{ "argv": [ "/opt/conda/envs/myenv/bin/python", "-m", "ipykernel_launcher", "-f", "{connection_file}" ], "display_name": "myenv", "language": "python" }

这个 json 文件的第一行就是内核启动时要执行的 Python 解释器路径。百分之八十的 kernel error 都出在这里：路径指向的解释器不存在、被移动了、或者那个解释器里没装 ipykernel、再或者 ipykernel 装了一半损坏了。所以排查第一步永远是先看这个路径到底存不存在、能不能正常运行。

2.2 重建内核的标准操作，照着抄就行

如果确认是内核注册表指向的解释器出了问题，最快的方式是重建内核。假设你想给名为myenv的 conda 环境注册一个内核：

conda activate myenv pip install ipykernel # 确保 ipykernel 存在且是最新版本 python -m ipykernel install --user --name myenv --display-name "Python (myenv)"

注意这里的逻辑顺序：先激活目标环境，再用该环境里的 python 执行-m ipykernel install。这样注册出来的内核，argv 里的路径一定指向myenv的 Python，不会张冠李戴。如果你用的是 venv，同理：

source venv/bin/activate # Windows 是 venv\Scripts\activate pip install ipykernel python -m ipykernel install --user --name myvenv --display-name "Python (myvenv)"

装完后再次执行jupyter kernelspec list，然后回浏览器刷新页面，在 Change Kernel 里应该能看到新名字。这里要提醒一个细节：--user参数只对当前用户生效，如果你之前是 root 或者在 Docker 里，可能需要不加--user直接写入系统目录，或者换成--prefix指定安装位置。

2.3 conda 和 venv 混用引发的经典踩坑

我见过最典型的翻车操作是这样的：用户先用 conda 建了一个环境，装好了 ipykernel，注册了内核；后来觉得 conda 太占空间，又把原来那个环境删了，重新用 venv 建了一个同名目录。结果 kernelspec 里记录的还是老路径，指向一个已经不存在的 Python，Jupyter 一点启动就直接 kernel error。

还有一种更隐蔽的：用户在不同终端里先后激活了不同环境，在 A 环境启动了 Jupyter Notebook，然后在 B 环境安装了新的包，重启内核后却想用 B 的包——当然找不到。这其实是用户层面的环境认知问题，但表现出来就是"内核报错、模块导入失败"。

我的建议是：一个项目固定一个环境，环境创建后不要轻易移动或删除，kernel.json 的路径要当作配置资产来管理。如果确实想清理环境，先执行jupyter kernelspec remove 内核名把注册表清理干净，再删环境目录，避免留一堆僵尸内核。

3. 专治 Windows 下 DLL 加载失败：以 rpds 报错为例

3.1 为什么 Jupyter 进程会报 DLL load failed

热搜词里有一条很具体："运行 jupyter notebook 出现 importerror: dll load failed while importing rpds"。这个报错在 2024 年前后集中爆发过一波，典型场景是 Python 3.12 或 3.13 在 Windows 上跑 Jupyter，启动内核时突然炸出：

ImportError: DLL load failed while importing rpds: 找不到指定的模块。

要理解这个错误，得先知道 rpds 是什么。rpds 是rpds-py这个库，全称大概是"Rust Python Delayed Set"，它用 Rust 实现了一组高性能数据结构的 Python 绑定，是jsonschema、referencing等一堆库的底层依赖。问题就出在"Rust 实现的 Python 绑定"上：这类扩展包必须在特定 Python 版本和特定系统架构下编译或下载对应的 wheel 文件才能正常工作。

如果rpds-py的版本太老，没有匹配你当前 Python 3.12/3.13 的预编译 wheel，pip 就会尝试从源码编译。而编译 Rust 代码需要 Rust 工具链，Windows 上大部分人没装，或者装了但缺一些链接组件，最终就产出半成品——安装时没报错，导入时才炸出 DLL 加载失败。

3.2 完整排查链路，复现一遍你就有数了

遇到这种报错，我的排查顺序是固定的：

第一步，确认报错能否独立复现。在命令行直接执行：

python -c "import rpds; print(rpds.__version__)"

如果这里就报 DLL load failed，说明问题在包本身，和 Jupyter 没有关系，Jupyter 只是受害者。如果这里不报错，说明是 Jupyter 启动时用了另一个 Python 环境——回到第 2 节的 kernelspec 排查。

第二步，确认版本和 wheel 信息：

pip show rpds-py pip debug --verbose | findstr "cp312"

pip debug --verbose能看到当前解释器支持哪些 wheel 标签，比如cp312-cp312-win_amd64。然后对比rpds-py的当前版本，如果版本落后比较多，大概率就是没有匹配的 wheel。

第三步，执行最直接的治疗：

pip uninstall rpds-py -y pip install --upgrade rpds-py

升级后重复第一步的导入测试。新版 rpds-py 通常带上了 Python 3.12/3.13 的预编译 wheel，装上就能跑。这一步解决了我遇到的全部 rpds 报错案例。

3.3 干净修复：版本对齐，而不是盲目升级整个环境

有一点要特别强调：遇到 rpds 报错时，不要去升级 Jupyter、升级 jsonschema、或者干脆重装 Python——这些操作很可能把事情搞得更复杂。rpds-py 是底层依赖，很多库要求它存在，但不同库对它的版本范围要求不同，贸然升级可能引发新的依赖冲突。

正确做法是只针对报错的包做版本对齐。如果pip install --upgrade rpds-py之后还是报 DLL 错，接下来检查两个方向：

• 缺少 Visual C++ Redistributable。Windows 上很多 Python 扩展包都依赖这个运行库，没装的话任何 DLL 导入都可能失败。去微软官网装最新的 VC_redist.x64.exe 就行，不用反复装，装一次通用。
• 架构不匹配。确认你的 Python 是 64 位还是 32 位，jupyter 和 rpds 都要用一致架构。现在绝大多数人都是 64 位，但如果你的环境是 Anaconda 老版本装出的 32 位解释器，也会出现奇怪的 DLL 错误。

我还遇到过一种边缘情况：conda 环境里的 rpds-py 和 pip 安装的版本互相覆盖，导致目录里同时存在残留文件。这种情况建议直接在 conda 环境里用conda install -c conda-forge rpds-py统一管理，避免混用。

4. 单元格执行没反应和一直转圈的另类原因

4.1 浏览器和内核之间的通道断了

有时候内核其实活着，进程也没崩，但你在浏览器里点运行，单元格就是一直转圈，或者干脆没有任何反应。这种问题的根源经常不在内核，而在于前端界面和内核进程之间的通信通道。

Jupyter 的前后端通信走的是 WebSocket，浏览器通过一个随机的连接文件（{connection_file}）与内核进程建立连接。中间任何一个环节断了，前端就"失聪"了。常见的断开原因有三个：电脑休眠后网络连接重置、Jupyter 服务端重启过而浏览器还保留旧的标签页、浏览器扩展拦截了 WebSocket 请求。

遇到这种问题，最简单的办法是刷新浏览器页面。如果刷新没用，进 Kernel -> Restart Kernel，强制重建连接。大部分前端失联问题这两步都能解决。如果还不行，尝试在启动 Jupyter 的终端里按 Ctrl+C 停掉服务，重新启动，然后重新打开 notebook 页面。

4.2 Token 过期和端口冲突这两个隐藏坑

Jupyter Notebook 从 4.x 版本开始默认启用 Token 认证。启动时终端会打印一个带 token 的 URL，类似：

http://localhost:8888/?token=8f8b1e1e8a4e4e4e8f8b1e1e8a4e4e4e

如果你把浏览器标签页存了书签，隔了很久再打开，token 可能已经失效了，或者服务器重启后 token 换了，但你的收藏夹还是旧地址。此时打开的页面虽然能显示出来，但执行任何操作都可能没有反应，或者新建内核时一直 starting。解法很简单：回到启动 Jupyter 的终端，复制新的带 token 的 URL，或者手动输入 token（登录框里有输入位置）。

端口冲突也特别常见。默认端口 8888 被其他程序占了，Jupyter 会自动换到 8889，但你浏览器里打开的恰恰是 8888 的旧标签页，于是看到的是一个完全不同的服务或者报错页面。Windows 上用这个命令快速查看端口占用：

netstat -ano | findstr :8888

如果确认被占用，可以指定端口启动：

jupyter notebook --port 9999 --no-browser

然后手动打开http://localhost:9999。

4.3 用命令行直接验证内核是否健康

很多前端问题让人摸不着头脑，我推荐一个非常实用的验证手段：绕过浏览器，直接用命令行连接内核。Jupyter 官方提供了一个控制台客户端，执行：

jupyter console --kernel python3

如果这个能正常出现In [1]:提示符并执行代码，说明内核进程本身是健康的，问题必然出在浏览器端或者 WebSocket 通道。如果这里也卡住或者报错，那才是真正的内核层故障。

更进一步，你还可以用jupyter execute这种无头方式直接执行一个 notebook 文件：

jupyter execute my_notebook.ipynb --kernel python3

这个命令会完整走一遍"启动内核→执行代码→收集输出→关闭内核"的流程，如果它能跑通，几乎可以断定环境没问题，回到前端去找原因。我在很多"swear to god 内核没问题但网页就是不跑"的场景里，就是用这一招确认清白，然后花时间排查浏览器插件和网络代理的。

5. 网页版、NVIM、自动补全：冷门但真实的连带故障

5.1 网页版 Jupyter 的会话残留与权限问题

"jupyter notebook 网页版"这个热搜词覆盖面很广，有人指的是局域网内通过浏览器访问服务器上的 Jupyter，有人指的是在 Docker 容器里跑的部署版。这类场景有一个共性：前端在浏览器里，后端在远程，中间隔了网络、反代、容器，任何一层出问题都会被误判成 kernel error。

远程场景下我遇到最多的是会话残留问题。上次内核没正常关闭，在服务端留下了一个僵死的 kernel 进程，占着通信端口。新请求尝试连接同一个端口，一直 starting，老的进程又不释放资源。这种情况去服务器上执行jupyter kernelspec list没有意义，要看进程列表：

ps aux | grep kernel

Windows 上则是：

tasklist | findstr python

把残留的 kernel 进程结束掉，然后在网页菜单里 Kernel -> Shutdown All Kernels，再重启内核就好了。这里要提醒：网页版的"重新启动"按钮有时只清了前端状态，没有清后端进程，所以直接去服务器上杀进程才是根治。

Docker 部署还有一层权限坑。容器里跑 Jupyter 的用户和挂载卷的宿主用户 UID 不一致时，内核启动后写入配置目录（~/.local/share/jupyter）会失败，表现就是内核像睡着了一样没有任何反应。处理方式是在docker run时指定--user参数，或者在镜像里调整目录属主。如果你用的是现成的 jupyter/docker-stacks 镜像，注意挂载数据卷时把权限对齐，别让卷目录对容器用户不可写。

5.2 NVIM 插件调用的是哪个 Python：一个很容易忽略的问题

"jupyter notebook nvim"能进热搜，说明有不少用户在 Neovim 里折腾 Jupyter。常见的方案有jupyter-nvim、nvim-jupyter、还有用conjure搭配 Python 内核的。这类插件本质上是在编辑器里起一个 Jupyter 客户端，把代码发到内核执行，再把返回结果展示在编辑器里。

这类插件踩坑最多的地方，是插件默认调用的jupyter命令和你实际使用的环境不一致。比如你的 Neovim 是通过 Homebrew 或 apt 装的，它带的 Python 是系统自带的，系统路径里只有一个老版本 jupyter；而你项目的代码需要 conda 环境myenv里的 Python 3.11。插件用系统 jupyter 起内核，结果要么起不来，要么起来一个缺包的老内核，报错一个接一个。

解决办法是在插件配置里显式指定内核和解释器路径。拿 nvim-jupyter 举例，检查一下你的配置里是否有类似这样的设置，确保它指向你想要的 python：

-- 在 init.lua 或配置文件中 require('nvim-jupyter').setup({ python_cmd = '/opt/conda/envs/myenv/bin/python', jupyter_cmd = '/opt/conda/envs/myenv/bin/jupyter', })

另一个 NVIM 场景常见问题是：notebook 文件里的 metadata 记录了它上次运行时的 kernelspec 名字，换电脑或换环境后，notebook 打开后自动选择了一个不存在的内核。这时需要在 Jupyter 界面里重新选内核，或者直接编辑ipynb文件里metadata.kernelspec字段，把它改成jupyter kernelspec list里实际存在的名字。

5.3 自动补全失效，根因往往还是内核

"jupyter notebook 代码自动补齐"也是一个高频搜索，而且很多人不知道自动补全和内核健康度是强相关的。Jupyter 的补全分两部分：静态补全（基于 jedi 或 pyright）和动态补全（基于内核的complete_request）。动态补全必须通过内核完成，内核如果起不来、或者内核里的jedi版本有问题，补全就会失效。

所以当补全突然不好使的时候，先确认内核是否正常执行代码：跑一个print("test")看有没有输出。如果输出正常但补全还是消失，多半是jedi和当前 Python 版本不兼容，执行：

pip install --upgrade jedi

如果用的是 JupyterLab，还可以试试jupyterlab-lsp插件提供的语言服务器补全，它不依赖内核，即使内核挂了也能提供基本的静态补全。但记住，这类工具无法替代内核，核心还是把内核修好。

如果你是jupyterlab-lsp的老用户，补全失效还有一种特殊原因：语言服务器进程崩溃后没有自动重启。查看 Jupyter 终端日志里有没有 pylsp 相关的报错，有的话重启语言服务器或者升级python-lsp-server——它最近版本迭代挺频繁，老版本和新的jupyterlab-lsp组合容易出现兼容问题。

6. 提前设防：从"出了问题救火"到"根本不出问题"

6.1 环境隔离的规范，能免掉八成烦恼

回头看我处理过的所有 kernel 问题，绝大多数源于环境混乱：全局环境里塞了一堆互不兼容的包、多个 Python 版本共存、venv 和 conda 混用。如果从一开始就做好环境隔离，后面基本不会碰到这些幺蛾子。

我现在的规范很简单：

• 每个项目建独立虚拟环境（conda 或 venv 都行，但一个项目只选一个工具，不要混）
• 在环境内使用requirements.txt或environment.yml记录依赖，锁定主要版本
• 环境建好后，立即用python -m ipykernel install --user --name 项目名注册内核，并把 kernel 名写进项目 README
• 系统全局环境只装jupyter、notebook等启动器工具本身，业务依赖全部进虚拟环境

这套规范执行下来，我至少一年没再踩过环境级 kernel error。即使出了小问题，也能做到 5 分钟内定位到具体环境。

6.2 维护内核列表，定期给环境"体检"

内核列表就像桌面上的快捷方式，装得多了里面全是失效链接。建议隔一段时间清理一次：

jupyter kernelspec list # 查看现有内核 jupyter kernelspec remove 旧名字 # 移除无效内核

清理时注意先确认这个内核是否还有项目在用，别误删。如果某个内核对应的环境已经删除了，那么这个内核必然失效，留着只会让 Change Kernel 菜单变得臃肿，还会让你在选内核时误选到坏项。

另外，升级 Python 大版本（比如 3.11 升 3.12）之后，一定要重新执行一遍python -m ipykernel install，因为旧内核注册表里指向的 ipykernel 可能是为老版本编译的，新解释器无法正常加载。这也是很多人在升级 Python 后突然发现 Jupyter 打不开的直接原因。

6.3 应急修复速查表，建议截图保存

最后给一张我在团队内部流传的速查表，按症状直接定位操作：

凭我几年的经验，这张表覆盖了九成以上的 Jupyter 内核故障。剩下那一成，大多数是硬件问题（内存爆了、硬盘坏了）或者极其冷门的库冲突，那种情况下把完整 traceback 发到社区问答平台，基本也能得到答案。

最后再分享一个长期有用的习惯

问题解决之后，强烈建议你花一分钟把这次事故的完整过程记录下来：当时是什么症状、执行了什么命令、根因是什么、最终怎么修的。这个习惯救过我很多次，因为 Jupyter 的 kernel 问题有一个特点——它很少只发生一次，而且每次原因可能都不完全相同。

我自己就建了一个简单的备忘录，按"症状关键词 + 日期 + 根因"的格式记录，现在遇到类似报错，翻一下历史就能秒定位。这两个月以来，找我要 kernel 问题解决方案的同事越来越少，因为我把速查表发他们之后，他们已经能自己搞定了。希望这篇笔记对你有同样的价值。