pip 装好了jupyter notebook 也敲进去了终端哗啦啦刷出一串 http://localhost:8888/tree?token一长串字符然后……浏览器一点动静都没有。 这个场景我见过太多次从实验室的 Ubuntu 工作站到公司配的 Windows 笔记本从 WSL 到云上的开发机本质上都是同一类毛病。所谓 Jupyter notebook 无法跳转网页九成以上不是服务没起来而是服务起来了最后一步把地址甩给系统浏览器这个动作断掉了。它不报红、不崩溃光标安安静静地闪最容易被误判成装坏了。这篇东西我按自己这几年排障的顺序来写先讲清楚 Jupyter 启动流程里到底哪一环会断再给出三条不同成本的修复路线应急手动进、配置文件根治、远程服务器专治然后连带把几个高频伴生问题一起收拾掉jupyter notebook 打不开、单元格执行代码没有任何反应、启动即崩的 ImportError: DLL load failed while importing rpds以及很多人升级之后突然消失的代码自动补齐和 Markdown 目录。适合刚装完 Jupyter 的新手也适合在服务器上折腾了半天还没看见界面的老手照着抄基本能落地。1. 先定位断点浏览器为什么没被拉起来1.1 Jupyter 启动流程里其实有三个独立环节很多人把启动 Jupyter当成一个黑盒动作其实它内部至少拆成三段每一段都可能单独失败而表现出的症状却几乎一样——网页没出来。第一段是服务端拉起。jupyter notebook本质上是启动一个基于 Tornado 的 HTTP 服务默认监听本机 8888 端口同时初始化一个内核管理进程。这一段失败的话你连那行带 token 的 URL 都看不到终端会直接抛异常退出。第二段是生成访问地址。服务起来之后Jupyter 会把协议、主机名、端口、token 拼成一个完整 URL打印到终端。这一段几乎是纯字符串拼接很少出问题但有一个坑如果 8888 被占用它会自动往后找 8889、8890……终端打印的是新端口而你书签里存的还是 8888打开就是一片空白或者拒绝连接。第三段才是调用系统浏览器。这一步落在 Python 标准库的webbrowser模块上它先看环境变量BROWSER有没有指定命令没有就去查系统默认浏览器关联然后 fork 一个进程把 URL 丢过去。Jupyter 里对应的是open_browser和browser这两个配置项。绝大多数无法跳转网页的问题断点都在第三段。提示判断断点有个很土但很好用的办法——看终端有没有打印出带 token 的完整 URL。有 URL说明前两段都正常问题在浏览器调用没有 URL问题在服务端方向完全不同。1.2 三类症状对应三种修法我把常见情况整理成一张表你可以先对号入座再往下翻对应章节能省不少时间。终端表现断点位置推荐修法对应章节打印出 URL浏览器完全不弹浏览器调用失败手动复制 URL或改配置文件第 2、3 章打印出 URL浏览器弹了但拒绝连接主机名解析或端口漂移用 127.0.0.1 替换 localhost检查实际端口第 4 章浏览器打开提示要 token 或 403鉴权环节从jupyter notebook list里复制完整 URL第 5 章命令直接报 ImportError 退出依赖环境损坏重装依赖检查 pip 与 Python 位数第 5 章页面能进单元格跑不动内核通信检查 ipykernel、重启内核第 5 章这张表我建议先截图存一下。因为后面你在排查过程中症状是会变的——比如你手动进了网页结果发现单元格转半天不动那不是同一个问题别在一个方向上死磕。1.3 为什么老手都倾向于关掉自动弹浏览器说个反直觉的经验在真正长期用 Jupyter 的人手里open_browser往往是主动关掉的。原因是自动弹浏览器这件事本身很脆弱——默认浏览器换了、系统关联坏了、环境变量脏了都会失效而它对生产力的贡献其实很小。你只要有一个固定的 URL记下来或者写个别名手动点一下书签的成本远低于每次去修webbrowser。所以我的建议是先按第 2 章把手动路径打通再决定要不要花时间修自动弹出。把修复顺序倒过来容易在小概率问题上耗掉一晚上。2. 三分钟应急方案不折腾配置直接进网页2.1 手动复制 URL 是最稳的一招终端打印的那行 URL完整长这样http://localhost:8888/tree?token8f3a1c9e7b2d4f6a0e5c8b1d3a7f9e2c4b6d8a0f1e3c5b7d注意一定要连?token后面那串一起复制长度通常在 48 位左右。只复制http://localhost:8888的话新版 Jupyter 会把你拦在一个要求输入 token 或密码的页面上看起来就像打不开。另外终端里这行 URL 是可以直接选中右键复制的在大多数终端里不用手打。如果你已经不小心关掉了终端输出可以在另一个终端窗口里执行jupyter notebook list它会列出当前正在运行的所有服务包含完整的带 token URL。更新一点的版本可能提示你用jupyter server list两个命令在多数发行版上都能用。2.2 主动加 --no-browser把不弹浏览器变成预期行为如果你已经确认自动弹浏览器在自己机器上就是不灵别跟它较劲直接在启动命令里声明放弃jupyter notebook --no-browser这么写有两个好处。一是心理上不别扭了它本来就不该弹你手动开二是有些自动化脚本、系统服务、容器环境里webbrowser调用本身会拖慢启动甚至卡住加上这个参数启动明显更干脆。2.3 固定端口和监听地址的完整启动命令端口漂移是我明明存了书签却打不开的元凶所以顺手把端口钉死jupyter notebook --no-browser --port8888 --ip127.0.0.1这里--ip127.0.0.1表示只监听本机回环地址只有这台机器自己能访问最安全。如果你是在自己家里或可信内网里想让同网段的另一台电脑也能连上可以用--ip0.0.0.0但请务必确认 token 没被人看到、密码也设了。jupyter notebook password这个命令会提示你输入两遍密码它把哈希值写到配置文件里之后访问只需要密码不用每次从终端复制 token。我个人强烈建议设一个尤其是用--ip0.0.0.0的时候否则同一个网络里任何人拿到那行带 token 的 URL 就能执行你的代码。3. 根治自动弹出配置文件怎么改才对3.1 先把配置文件生成出来并记住它的路径Jupyter 默认不会帮你建配置文件你要主动生成jupyter notebook --generate-config它会打印出文件的完整路径典型位置是Linux / macOS~/.jupyter/jupyter_notebook_config.pyWindowsC:\Users\你的用户名\.jupyter\jupyter_notebook_config.py如果这个文件已经存在命令会问你Overwrite这时候一定选 No不然你之前配的东西全没了。这也是我踩过的一个坑早期不懂一路回车把好不容易调好的配置覆盖了白干两小时。3.2 NotebookApp 和 ServerApp到底该写哪个这是最容易让人懵的地方。Jupyter 历史上有两套配置命名取决于你的版本版本区间核心配置类配置文件典型场景Notebook 6.x 及更早NotebookAppjupyter_notebook_config.py老教程、老项目Notebook 7.x / JupyterLabServerAppjupyter_server_config.py现在的默认安装Notebook 7.x 里的jupyter notebookNotebookApp继承 ServerAppjupyter_notebook_config.py混合情况实际操作时不用太纠结两行都写上互相不冲突c.ServerApp.open_browser True c.NotebookApp.open_browser True同理浏览器路径也可以两边都配。写完之后保存重启 Jupyter绝大多数配置不生效的疑问都源于只写了一边。3.3 browser 参数里那个 %s 是灵魂千万别删指定浏览器最标准的写法是这样c.ServerApp.browser /usr/bin/google-chrome %s c.NotebookApp.browser /usr/bin/google-chrome %sWindows 上路径要用双反斜杠或原始字符串c.ServerApp.browser C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe %s为什么末尾一定要带%s因为 Jupyter 底层用的是webbrowser模块的通用浏览器类它的工作方式是把%s当成占位符用实际 URL 替换掉之后再交给系统执行。你写成google-chrome而不带%s浏览器被启动了但没人告诉它该打开哪个页面结果就是浏览器弹出来了停在主页或空白页——这比不弹还让人困惑很多人以为配置成功了其实只是浏览器被拉了个空壳。还有一个细节如果你写的浏览器路径根本不存在webbrowser.get()会抛webbrowser.ErrorJupyter 捕获之后只在终端打一行 warning 就继续跑了不会中断启动。所以一定要回头看终端输出里有没有类似No web browser found的字样那是明确线索。3.4 顺手把根目录和端口也定下来既然都打开配置文件了索性一次配好省得以后来回加参数c.ServerApp.root_dir /home/yourname/notebooks c.ServerApp.port 8888 c.ServerApp.ip 127.0.0.1 c.ServerApp.open_browser Trueroot_dir建议单独设成一个固定目录好处是启动时不会因为你在哪个路径下敲命令而看到不同的文件树——这个文件列表怎么变了的疑问也是新手高频困惑之一。注意改了root_dir之后之前的相对路径引用可能失效先把重要的 notebook 挪过去再改。注意配置文件是 Python 文件缩进和引号必须合法。写错一个引号Jupyter 启动时会报语法错误并直接退出。改完先用python -c exec(open(配置文件路径).read())检查一下语法能省一次莫名其妙的启动失败。4. 远程服务器、WSL 和 localhost 解析的连锁坑4.1 没有图形界面的机器根本弹不出浏览器在服务器上跑 Jupyter 是常态而服务器通常没有桌面环境webbrowser找不到任何可用浏览器于是无法跳转网页变成了必然结果不是故障。这种情况下唯一正确的姿势是服务器端用--no-browser跑然后在你自己的本地电脑上访问。但直接访问http://服务器IP:8888通常也不通因为防火墙和绑定地址都不允许。有两种正规做法一是服务器上--ip0.0.0.0加上防火墙放行该端口内网可信环境才这么做二是走本地端口转发。前者配置简单但暴露面大后者更安全我一般推荐后者。4.2 SSH 端口转发的具体写法在你自己的电脑上开一个终端执行ssh -L 8888:127.0.0.1:8888 你的用户名服务器地址这条命令的意思是把你本地 8888 端口的流量通过这条 SSH 连接转到服务器上的 127.0.0.1:8888。连上之后这个 SSH 窗口必须一直开着然后在本地浏览器访问http://127.0.0.1:8888就能看到界面。服务器那一侧Jupyter 用默认绑定启动就行jupyter notebook --no-browser --port8888这里有个顺序问题要注意先建好 SSH 转发再启动 Jupyter 也可以反过来也行但两端端口必须一致。如果你本地 8888 已经被别的服务占了把本地那侧换成 9999ssh -L 9999:127.0.0.1:8888 userhost然后浏览器访问 9999。4.3 localhost 解析到 IPv6 导致的拒绝连接这个坑很隐蔽值得单独说。在部分 Linux 发行版和某些系统配置下localhost会优先解析成 IPv6 的::1而 Jupyter 默认监听的是 IPv4 的127.0.0.1。结果就是浏览器地址栏里http://localhost:8888转圈或者直接报无法访问此网站你换成http://127.0.0.1:8888就正常了。排查这一步只需要一条命令看服务到底监听在哪个地址上ss -lntp | grep 8888或者netstat -ano | findstr 8888输出里如果是127.0.0.1:8888那浏览器就用127.0.0.1如果是[::1]:8888那就要用localhost或者[::1]。养成用127.0.0.1而不是localhost的习惯能规避掉一整类玄学问题。还有一种情况你在 WSL 里跑 Jupyter从 Windows 侧的浏览器访问localhost:8888。较新的 WSL2 版本做了本地端口转发一般能通如果通不了先在 WSL 里确认ss -lntp看到的是0.0.0.0:8888而不是127.0.0.1:8888绑定到回环地址的话Windows 侧是访问不到的。5. 打不开、报错、跑不动高频故障逐个拆5.1 ImportError: DLL load failed while importing rpds 到底怎么回事这个报错近两年出现频率很高症状是你在 Windows 上敲jupyter notebook命令还没开始跑服务就直接崩了堆栈最后一行是ImportError: DLL load failed while importing rpds。先说原理。rpds是一个用 Rust 写的不可变数据结构库通过referencing被新版jsonschema依赖而jsonschema是 Jupyter 生态里校验 notebook 格式的基础组件。它在 Windows 上是以预编译扩展模块.pyd的形式分发的这个二进制必须和你的 Python 版本、位数严格匹配。常见的三种触发原因一是 pip 版本太老在挑选安装包时没选对符合当前解释器标签的构建版本装了个不匹配的二是 Python 装的是 32 位版本而对应的 32 位构建缺失或者被跳过最终回退到源码编译编译环境又不全三是安装过程中断过文件残缺或者杀毒软件误删了 .pyd 文件。对应的修复顺序我按成功率从高到低列一下python -m pip install --upgrade pip setuptools wheel python -m pip install --force-reinstall --no-cache-dir rpds-py先确认 pip 是不是最新的这一步最关键很多问题在这一步就没了再强制重装。装完立刻验证python -c import rpds; print(rpds.__file__)能打印出路径就说明这个模块通了再跑jupyter notebook试试。如果还是不行检查一下 Python 位数python -c import platform; print(platform.architecture())输出里如果看到32bit建议直接换成 64 位 Python 重装环境32 位在数据科学生态里支持越来越差早换早省心。实在绕不过去还有个釜底抽薪的办法——把引入rpds的那条依赖链降级掉python -m pip install jsonschema4.18referencing和rpds是新版 jsonschema 才引入的降回 4.17 系列就不会触发这个导入。这个做法牺牲一点新特性但能立刻让环境跑起来属于典型的先治病再调养。5.2 页面能打开但提示 token 无效或 403通常是你手动改了地址栏把?token那一段删掉了或者 token 复制时截断了。另一个常见原因是服务重启之后 token 变了而你浏览器里还开着旧页面刷新。解决办法是回到终端重新复制完整 URL或者干脆设置密码jupyter notebook password设置之后会往jupyter_server_config.json里写一条哈希记录就不再依赖 token 了。还有个小概率情况你开了多个 Jupyter 实例端口不同、token 不同混着用就串了。用jupyter notebook list看清楚当前到底跑着几个。5.3 端口被占用导致地址漂移如果 8888 被别的程序占着Jupyter 默认会尝试往后找端口port_retries默认为 50。它不会报错只会在终端打印一个新端口号。你如果习惯性地访问 8888看到的可能是另一个服务的页面或者连接被拒绝。排查方法很直接ss -lntp | grep -E 888[0-9]|889[0-9]Windows 上用netstat -ano | findstr 888要么把占用端口的进程关掉要么在配置里钉死端口并接受它启动失败时明确报错别让它悄悄漂移。5.4 单元格执行代码没有任何反应这个症状和浏览器没关系是内核层面的问题。表现是单元格前面的方括号里显示[*]一直不变成数字或者点运行完全没动静。排查顺序我一般这么走先看右上角的内核指示器是不是显示成No Kernel或者一直转圈如果是说明前端和后端根本没连上。接着在终端里看有没有内核进程报错日志。然后重点检查当前 notebook 选的解释器环境里有没有装ipykernelpython -m pip install --upgrade ipykernel jupyter_client python -m ipykernel install --user --name myenv --display-name Python (myenv)很多人的问题是在 A 环境里装了 jupyter在 B 环境里装了 pandas用 A 的 jupyter 打开 notebook选的内核却是 A 的 Pythonimport pandas 当然失败表现就是代码没反应。注册一个带名字的内核然后在界面上明确选它这个坑能一次性解决。另外一个容易被忽略的原因是安全软件拦截了本地回环的 WebSocket 连接。前端和内核之间的实时通信走的是ws://协议某些企业级安全软件会把这类短连接当成可疑行为掐掉症状就是页面能开、代码不跑。这种情况在终端里往往能看到反复的连接断开日志换个网络环境或者调整软件规则就能验证。5.5 一张表收尾常见问题症状最可能原因一句话解法不弹浏览器有 URLbrowser 配置错或缺 %s手动复制 URL或修正配置不弹浏览器无 URL服务端启动失败看完整堆栈多半是依赖问题弹了但拒绝连接localhost 解析或端口漂移换 127.0.0.1确认实际端口提示要 tokenURL 不完整或 token 过期重新复制完整 URL 或设密码启动即崩报 rpds扩展模块不匹配升级 pip 后强制重装 rpds-py单元格不动内核未连通重装 ipykernel 并注册内核6. 顺手解决代码自动补齐和 Markdown 目录6.1 代码自动补齐先搞清楚你在用哪套界面很多人是升级 Jupyter 之后突然发现以前按 Tab 会提示现在不提示了本质上是扩展体系换了一整套。老的nbextensions体系里面有个叫 Hinterland 的补全扩展只兼容 Notebook 6 及更早版本而 Notebook 7 和 JupyterLab 用的是完全不同的前端框架老扩展直接失效。方案适用版本安装要点体验评价JupyterLab 内置补全Lab 3无需安装Tab 触发够用不开箱即用但只补基础项jupyterlab-lspLab 3需配套安装语言服务器补全最全能跳转定义配置略麻烦Hinterland 扩展Notebook 6 及更早装 nbextensions 后勾选老环境专属装完即生效换用编辑器插件任意在 Neovim/VSCode 里连内核适合重度键盘党想上 LSP 的话大致是这两步python -m pip install jupyterlab-lsp python-lsp-server[all]装完重启 JupyterLab在设置里确认补全功能开着。python-lsp-server[all]这个方括号别省不带的话只装最基础的语言服务很多补全项出不来。6.2 给 Markdown 单元格生成目录先说一个零依赖的做法Jupyter 渲染 Markdown 单元格时会把标题转换成 HTML 锚点所以你可以直接手写链接跳转。锚点的生成规则很朴素——标题文字全部转小写、删掉标点符号、空格换成连字符。比如标题是## 2. 核心细节去掉标点和空格后锚点就是#2-核心细节写法[跳到第 2 节](#2-核心细节)中文标题也能正常生成锚点这一点不用怀疑。唯一要注意的是标点会被删掉、空格会变连字符写的时候对着规则推一遍就行。如果想要自动生成的目录Notebook 6 环境可以装jupyter_contrib_nbextensions然后在界面里勾选 Table of Contents (2)它会常驻一个侧边栏实时跟随滚动位置高亮当前章节。Notebook 7 或 JupyterLab 环境下用jupyterlab-toc插件效果类似。升级到 7 之后老目录扩展消失也是同一个原因——扩展体系不兼容。6.3 在 Neovim 里连 Jupyter 内核如果你本来就是 Neovim 用户其实有一条更省事的路不打开浏览器界面直接在编辑器里连 Jupyter 内核跑代码。常见做法是配合jupytext把 .ipynb 和 .py 双向转换方便用 Git 管理加上iron.nvim或者jupyter-vim这类插件。jupyter-vim的工作方式是连到一个正在运行的 Jupyter 服务上通过它的接口把单元格发给内核执行结果回显在编辑器里。所以对你来说启动命令就是那个熟悉的jupyter notebook --no-browser --port8888注意这种情况下完全不涉及浏览器跳转你也不需要修open_browser。如果你日常已经有 Neovim 工作流与其纠结浏览器为什么弹不出来不如直接换成编辑器内执行一步到位。当然代价是失去了部分可视化输出画图类的分析还是得回到网页界面看。7. 这些年我在环境配置上踩过的坑7.1 把环境和配置当成两件事来管我刚开始用 Jupyter 的时候所有东西都装在系统 Python 里出了问题就重装重装完又出别的问题。后来改成每个项目一个虚拟环境jupyter本身装在基础环境ipykernel在项目环境里装并注册问题一下少了一大半。核心原则是Jupyter 是容器内核是内容两者分开管理。python -m venv .venv source .venv/bin/activate python -m pip install ipykernel python -m ipykernel install --user --name project-a --display-name Python (project-a)这样每个项目的依赖互不干扰删项目的时候把这个内核名字一起清掉就行jupyter kernelspec list jupyter kernelspec remove project-akernelspec list这个命令值得记住它能告诉你现在界面上那些内核名字分别指向哪个 Python是排查为什么 import 不到包的第一现场。7.2 配置文件改动之前先留副本jupyter_notebook_config.py这东西一旦配顺手了里面会积累很多东西根目录、端口、浏览器路径、禁用某些扩展、各种超时参数。我现在的习惯是改之前先复制一份带日期后缀改错了直接换回来。cp ~/.jupyter/jupyter_notebook_config.py ~/.jupyter/jupyter_notebook_config.py.bak听起来很土但当你排查了半天发现问题出在自己三天前加的一行配置上时这个习惯能救你一命。顺带提一句Windows 上这个隐藏目录在资源管理器里默认看不到路径框里直接输入%USERPROFILE%\.jupyter回车最快。7.3 别用管理员或 root 跑 Jupyter用 root 启动 Jupyter生成的文件属主是 root之后你用普通账号改文件就会权限报错而且是在你最不想被打断的时候报。更麻烦的是如果开了--ip0.0.0.0等于把这台机器上最高权限的执行入口挂到了网络上。这是绝对要避免的操作没有任何便利性值得拿这个换。7.4 关于换台机器就好使这件事同一个 notebook换一台电脑就一切正常说明问题几乎肯定在配置或依赖不在代码。这时候别去改代码直接做三件事对比pip list的输出、Python 版本和位数、.jupyter目录下的配置文件内容。我一般用 diff 工具直接比两边的pip freeze结果五分钟内基本能锁定是哪个包版本不一致。这个思路用久了你会发现 Jupyter 的绝大多数诡异问题都只是环境差异的外在表现。浏览器弹不出来这件事也是一样——它不是玄学只是启动流程里某一环的环境前提没被满足。把流程拆开一段一段确认问题自然就浮出来了。
