做数据分析的人基本都碰过这个场景代码写了一半正打算跑个结果看看单元格却一直卡在 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 error内核进程启动后立即崩溃退出环境依赖、DLL 加载、Python 版本一直显示Kernel starting, please wait...内核进程活着但迟迟没有向前端报告我已就绪通信串口被占用、jupyter_client 版本不匹配、启动脚本卡住单元格执行没有任何反应连报错都没有前端与内核的 WebSocket 通道断了浏览器标签页过期、端口冲突、内核已被 culling 杀掉终端里启动 Jupyter 时报ImportErrorJupyter 本体都起不来包安装损坏、Python 环境路径错乱这里要先提醒一句热搜词里那个 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 里记录的还是老路径指向一个已经不存在的 PythonJupyter 一点启动就直接 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 的预编译 wheelpip 就会尝试从源码编译。而编译 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 cp312pip 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 的终端里按 CtrlC 停掉服务重新启动然后重新打开 notebook 页面。4.2 Token 过期和端口冲突这两个隐藏坑Jupyter Notebook 从 4.x 版本开始默认启用 Token 认证。启动时终端会打印一个带 token 的 URL类似http://localhost:8888/?token8f8b1e1e8a4e4e4e8f8b1e1e8a4e4e4e如果你把浏览器标签页存了书签隔了很久再打开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 kernelWindows 上则是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 应急修复速查表建议截图保存最后给一张我在团队内部流传的速查表按症状直接定位操作症状首选检查快速修复命令红色 Kernel error无具体 traceback看启动 Jupyter 的终端日志jupyter kernelspec list检查路径Kernel starting 一直转圈确认 kernelspec 指向的解释器存在python -m ipykernel install --user --name env单元格执行没反应刷新浏览器、重启内核确认 token 地址检查端口占用ImportError: DLL load failed while importing rpds单独import rpds复现pip uninstall rpds-py pip install --upgrade rpds-py内核能启动但导入模块失败确认当前内核对应的 Python 环境Change Kernel切换或重建内核网页版连接超时服务器进程是否存活ps aux | grep kernel清理僵尸进程NVIM 里内核起不来插件配置的 python 路径配置python_cmd为绝对路径自动补全失效先跑print(test)验证内核pip install --upgrade jedi凭我几年的经验这张表覆盖了九成以上的 Jupyter 内核故障。剩下那一成大多数是硬件问题内存爆了、硬盘坏了或者极其冷门的库冲突那种情况下把完整 traceback 发到社区问答平台基本也能得到答案。最后再分享一个长期有用的习惯问题解决之后强烈建议你花一分钟把这次事故的完整过程记录下来当时是什么症状、执行了什么命令、根因是什么、最终怎么修的。这个习惯救过我很多次因为 Jupyter 的 kernel 问题有一个特点——它很少只发生一次而且每次原因可能都不完全相同。我自己就建了一个简单的备忘录按症状关键词 日期 根因的格式记录现在遇到类似报错翻一下历史就能秒定位。这两个月以来找我要 kernel 问题解决方案的同事越来越少因为我把速查表发他们之后他们已经能自己搞定了。希望这篇笔记对你有同样的价值。