Jupyter Notebook 从入门到工程化：安装、内核与故障排查

1. 先把 Jupyter Notebook 到底是什么讲透1.1 它不是网页版 Python而是能留住现场的实验台很多人第一次接触 Jupyter Notebook是被网页版这三个字骗进来的以为它就是个跑在浏览器里的 Python 解释器。实际上它的本质是一个把代码、运行结果、文字说明、图表全部封存在同一个文件里的交互式计算环境。这个文件就是.ipynb名字里的 ipynb 正是从 IPython Notebook 继承下来的历史包袱——2014 年项目从 IPython 里拆出来改名 Jupyter取的是 Julia、Python、R 三个名字的组合但文件后缀没跟着改一直留到今天。所以你在搜索框里输入 IPython Notebook翻出来的资料大多是 2015 年前后的老帖命令写法、配置项位置、扩展兼容性都和现在差得很远这一点先记住能省下大量试错时间。它能做的事用一句话概括把你敲一行命令、看一个结果、再决定下一步的探索过程完整地保存在一个可重复运行、可分享、可导出的文档里。做数据分析的人拿它清洗表格、画分布图写 Python 爬虫的人拿它一段段调试请求和解析逻辑学算法的人在里面手推 01 背包动态规划的口诀表、跑层次聚类的树状图做教学的人把讲解文字和可执行代码写在一起学生点一下就能看到结果。这些场景的共同点是过程比结果更重要而传统的.py脚本只留下结果中间那些我试了三种写法的痕迹全丢了。适合读下去的人大致是三类刚装完 Python、准备找第一个练手环境的新手用了一段时间但被单元格执行没反应打不开ImportError这些毛病反复折磨的熟手以及想把 notebook 纳入正式工作流、但不确定怎么和 VS Code、nvim、Git 打配合的老手。三类人的关注点完全不同我尽量分开讲你按需跳读。1.2 从 IPython 到 Jupyter哪些概念一直没变搞清楚几个老概念很多报错信息你就能读懂。IPython 时代留下的东西到今天还在用In [ ]和Out [ ]执行计数器和输出缓存。这个方括号里的数字不是装饰它是内核记录的执行序号也是很多诡异 bug 的源头后面第 3 章会专门拆。魔法命令以%开头的行魔法和%%开头的单元格魔法比如%timeit、%matplotlib inline、%%writefile。这套东西是 IPython 发明的Jupyter 全盘继承。内核Kernel真正执行你代码的那个 Python 进程。前端浏览器页面和内核之间靠 ZeroMQ 通信它们俩是两个独立的进程这个事实解释了一大半的卡住和没反应。ipykernel让 Python 能当 Jupyter 内核的那个包。你装jupyter notebook的时候它会作为依赖被带进来。.ipynb文件本身是个 JSON结构上分成cells、metadata、nbformat几大块每个 cell 里有cell_type、source、outputs、execution_count。输出结果是实实在在写进文件里的——这一点决定了它体积大、Git diff 难看、但也决定了你关掉浏览器再打开图还在那儿。理解了文件结构你后面遇到notebook 打不开、提示 JSON 解析失败就知道该去文本编辑器里翻尾部是不是被截断了。提示.ipynb的 JSON 里如果混进了非法字符常见于手改文件或者同步盘写入中断Jupyter 会直接拒绝加载。遇到这种情况先备份再用jupyter nbconvert --to notebook --nbformat 4 坏文件.ipynb尝试修复比在网上找在线修复工具靠谱得多。1.3 什么场景该用它什么场景趁早换工具我不太喜欢Jupyter 万能这种说法。它的优势是交互式探索和结果呈现短板同样明显场景用 Notebook换别的工具数据清洗、特征探索、画图非常合适—教学演示、算法过程可视化非常合适—爬虫调试请求参数合适—长期运行的定时任务不合适写成.py 系统计划任务上千行的业务模块不合适拆成包用 PyCharm / VS Code多人同时改同一个文件不合适拆模块或改用 Jupytext 转.py需要严格版本控制的代码库不合适Git 管.pynotebook 只做展示有个判断标准特别好用如果这个文件你三个月后还要回来改、还要给别人维护那就别用 notebook 当主载体。notebook 适合当草稿纸和实验记录成熟之后把稳定下来的函数抽到.py文件里notebook 只留调用和展示。这是我踩过坑之后最想说的一句。2. 安装与环境搭建把第一道坑挡在门外2.1 pip、conda、集成发行版三条路怎么选jupyter notebook 安装这个搜索词的热度一直很高说明卡在第一步的人非常多。目前主流有三条路第一条pip 直装。前提是你已经有一个能用的 Python建议 3.9 以上3.11 是目前兼容性比较舒服的一档。命令很简单python -m pip install --upgrade pip python -m pip install notebook装完敲jupyter notebook就能起。优点是干净、可控缺点是纯 pip 环境里科学计算相关的二进制包numpy、scipy、pyzmq 这类在某些平台需要自己解决编译依赖Windows 上偶尔会撞见 DLL 相关报错。第二条conda / mamba。数据科学圈的老牌选择二进制依赖由 conda 统一调度装 numpy、pandas、matplotlib 时省心很多conda create -n nb311 python3.11 conda activate nb311 conda install -c conda-forge jupyterlab notebook第三条各种 Python 集成发行版。装完自带 Jupyter、numpy、pandas 一大套适合完全不想折腾环境的新手。代价是环境体积大、包版本偏旧日后想单独升级某个库容易互相牵扯。我的建议很明确如果你打算长期写 Python走第二条或第一条 虚拟环境如果只是临时跑个教学 demo第三条也行但别指望它陪你走很远。注意pip 和 conda 混用是 DLL 报错的头号元凶。同一个环境里numpy 用 conda 装了、某个包又用 pip 拉了一个不同版本的 numpy 进来运行时就可能加载到错误的.dll/.so。选定一条路就尽量走到底实在要用 pip 装 conda 里没有的包装完跑一次pip check看有没有冲突。2.2 虚拟环境与内核注册这一步别偷懒新人最常犯的错是全局环境里堆了三十个包然后 notebook 里import cv2报找不到模块或者反过来装了两个版本的 Pythonnotebook 用的内核根本不是你刚装包的那个。正确姿势是每个项目一个虚拟环境然后把环境注册成 Jupyter 内核# 建环境 python -m venv .venv # 激活Windows .venv\Scripts\activate # 激活macOS / Linux source .venv/bin/activate # 装内核和常用包 pip install ipykernel jupyterlab pandas matplotlib # 注册成内核名字自己取显示名建议带上 Python 版本 python -m ipykernel install --user --namenb311 --display-name Python 3.11 (nb311) # 查看现有内核列表 jupyter kernelspec list--display-name里的版本号一定要写清楚。我见过太多人机器上有四个Python 3内核名字一模一样选错了就出现明明装了 pandas 却说没有的诡异现象。删除多余内核用jupyter kernelspec remove 内核名比手动去找 kernels 目录文件干净。另外一个细节注册内核时记录的是那个 Python 解释器的绝对路径。如果你后来把虚拟环境目录重命名或者删掉了notebook 里选这个内核就会启动失败报No such file or directory或者内核一直处于正在连接状态。这时候回终端jupyter kernelspec list看一眼路径就明白了。2.3 启动参数、配置文件与局域网访问裸敲jupyter notebook会做三件事启动服务、占用 8888 端口、自动打开浏览器。日常用没啥问题但有几个参数值得记住# 不自动开浏览器只打印访问地址 jupyter notebook --no-browser # 换端口8888 被占了的时候特别有用 jupyter notebook --port 8899 # 指定工作目录省得每次都 cd jupyter notebook --notebook-dir/Users/me/work想固定下来就生成配置文件jupyter notebook --generate-config它会在用户目录下的.jupyter文件夹里生成jupyter_notebook_config.py。用编辑器打开找到对应的行取消注释并改成你要的值。这里有个版本坑必须提醒老教程里写的都是c.NotebookApp.port、c.NotebookApp.ip这种写法但如果你装的是 Notebook 7 或者 Jupyter Server 2.x配置项已经搬迁到ServerApp下面了# 新版写法Notebook 7 / Jupyter Server 2.x c.ServerApp.ip 127.0.0.1 c.ServerApp.port 8888 c.ServerApp.open_browser False c.ServerApp.root_dir /Users/me/work c.ServerApp.token # 仅限本机自用见下方警告同时设NotebookApp和ServerApp两套值也不会报错但只有生效的那套起作用改完没反应多半就是改错了对象。想在同一个局域网里用手机或另一台电脑访问把ip改成0.0.0.0然后访问http://本机局域网IP:8888。这时候千万别把 token 设成空字符串——同一网络下的任何设备都能直接进你的文件系统风险很高。正确做法是设密码jupyter notebook password它会提示你输入两遍密码然后写进jupyter_server_config.json。之后访问时输入这个密码即可。密码本身也是哈希存储的比明文 token 好管理。提示如果你在某个云主机上跑 notebook更推荐的做法是只监听 127.0.0.1再用 SSH 端口转发把远端的端口映射到本地浏览器。命令是ssh -L 8888:127.0.0.1:8888 用户名主机地址这样流量全程加密也不用把端口暴露在公网上。这个方式的配置成本比想象中低值得花十分钟学一下。2.4 Notebook 7 和 classic 界面别被教程带偏2023 年之后pip install notebook装到的已经是 Notebook 7界面基于 JupyterLab 的组件重写过和经典的 Notebook 6 长得不一样。这个变化带来的实际影响有三条老一代的 nbextensions 扩展就是那个经典的 Nbextensions 配置页基本失效装上去也看不到标签页。快捷键有变化命令模式下的Esc进入、A上方插入、B下方插入、DD删除这些还好但部分插件快捷键没了。想找回经典界面的人可以装pip install notebook6.5.7但这条路的长期维护性堪忧新项目不建议回退。我个人现在的组合是JupyterLab 当主力多文件、多面板、终端一体Notebook 用来做单文件演示和交付。两个可以装在同一个环境里不冲突。3. 执行模型拆解单元格、内核和那个骗人的 In[ ]3.1 前端与内核分离顺序幻觉从哪来这是理解一切诡异现象的钥匙。你看到的浏览器页面是前端跑代码的是内核进程。前端把 cell 里的代码通过 ZeroMQ 发过去内核执行完把输出发回来前端渲染。这中间有三件事值得注意第一In [ ]里的数字只表示第几次被提交执行不表示依赖顺序。你先把第 3 个 cell 跑了再改第 1 个 cell 里的变量然后跑第 1 个最后从头Run All——中间那些结果可能是用旧变量算出来的。这就是所谓的 notebook 顺序幻觉它最恶心的地方在于你不重启内核就永远发现不了。第二输出是缓存下来的快照。你看到的那张图、那个 DataFrame是当时那一刻的结果。变量后来变了图片不会自己更新。第三内核是可以假死的。前端还在、cell 还能编辑但内核进程已经崩了或者卡在某个死循环里这时候你敲什么都是[*]没反应。对付这三条的办法说来简单但必须养成习惯每次要分享或提交结果之前执行Kernel → Restart Kernel and Run All Cells。跑得通说明这个 notebook 是自洽的跑不通说明你依赖了某个历史遗留变量。变量命名尽量不重复使用。同一个df前半段是原始数据、后半段是清洗结果这种写法早晚出事。大计算量的结果用完早点del掉并且%reset一下心里有数。3.2 单元格类型与魔法命令真正的高频工具一个 cell 有三种类型Code、Markdown、Raw。Markdown cell 支持标准 Markdown 加一部分 LaTeX写公式用$...$和$$...$$。大多数新手只用 Code cell把说明文字全都写成注释这是巨大的浪费——notebook 的价值有一半在 Markdown 里。一份好的 notebook读起来应该像一篇带可执行代码的报告而不是一堆代码加几行注释。魔法命令里我实际高频使用的就这么几个%timeit sorted(range(1000), keylambda x: -x) # 微基准测试自动决定重复次数 %%time # 整个 cell 计时看数据加载耗时够用 %matplotlib inline # 新版本默认就是 inline老环境里还得手动加 %config InlineBackend.figure_format retina # 高分辨率屏幕下图更清楚 %load_ext autoreload %autoreload 2 # 改动外部 .py 文件后自动重载开发模块时救命 %who / %whos # 查看当前命名空间里有啥变量排查顺序问题很好用 %reset -f # 清空所有变量比重启内核快%whos这个命令我要额外说一句。当你怀疑这个变量到底是不是我最新算的%whos会列出变量名、类型和值。配合%who_ls还能拿到变量名列表做批量清理比一个个del高效。另外提一个新手常问的问题Python 内置函数在 notebook 里怎么用和普通脚本完全一样。比如abs(-3.5)取绝对值int(42)、float(3.14)、str(100)做类型转换list 去重筛选可以用list(dict.fromkeys(...))或者set()这些在 cell 里随手就能试即时看到结果是 notebook 最舒服的地方。3.3 内存、缓存与变量的真实生命周期内核重启所有变量、导入的模块、定义过的函数全部消失。内核不重启它们就一直在内存里躺着。这两句话听起来像废话但它导致两个很实际的问题。一个是内存泄漏感。你反复加载了几个大 DataFrame、画了几十张图内存越吃越多最后内核被系统杀掉。判断方法是%whos看变量体积或者用psutil打印当前进程内存import os, psutil p psutil.Process(os.getpid()) print(f{p.memory_info().rss / 1024 / 1024:.1f} MB)另一个是 matplotlib 的图形对象堆积。画图时如果用plt.plot()而不关闭图会挂在全局状态上画到几百张之后渲染变慢。养成习惯每个 cell 里画完图加一句plt.show()需要多张独立图时用fig, ax plt.subplots()显式创建画完plt.close(fig)。还有个大坑是在 notebook 里定义了一个函数然后改了外部.py文件里的实现却忘了重启内核结果跑出来还是旧逻辑。这就是%autoreload 2存在的意义加上这两行模块级改动基本能自动生效注意已经被导入的具体对象引用不会变还是要重启。4. 提效三件套自动补全、目录、外部编辑器4.1 代码自动补全的几种实现路径jupyter notebook代码自动补齐这个词的搜索量说明默认体验确实不够好。分情况说Notebook 7 和 JupyterLab 4 自带补全。敲import pa之后按Tab或者等它自己弹就有候选列表了。这是在ipykernel里集成jedi实现的开箱可用。如果你的版本比较老Notebook 6默认只有Tab触发的有限补全想让它像 IDE 一样实时弹就得靠扩展。老版本装 nbextensions。注意只对 Notebook 6 有效pip install jupyter_contrib_nbextensions jupyter contrib nbextension install --user pip install jupyter_nbextensions_configurator jupyter nbextensions_configurator enable --user重启后首页会多一个 Nbextensions 标签里面把 Hinterland自动补全提示、Table of Contents (2)、Codefolding 这几个勾上。如果你装的是 Notebook 7这套东西不生效别浪费时间。JupyterLab 装 LSP 补全。想要跳转到定义查看函数签名重构这些 IDE 级别的功能装语言服务器pip install jupyterlab-lsp python-lsp-server[all]装完重启右键编辑器里能看到 LSP 相关菜单。这个方案在 JupyterLab 上体验接近 VS Code代价是首次加载稍慢大项目里内存占用会上来一点。VS Code 里写 notebook 是另一条路而且体验相当好装 Python 扩展和 Jupyter 扩展.ipynb文件直接打开补全是 Pylance 提供的比 jedi 强不少还能顺便用# %%把.py文件切成单元格跑。唯一的坑是内核选择——状态栏右上角一定要选对虚拟环境选错就出现模块找不到的假故障。我自己现在的分工是探索阶段用 VS Code 或 JupyterLab补全好、快捷键熟要出图和写讲解文字的时候切回 Notebook 界面渲染和排版更贴近最终交付形态。4.2 Markdown 目录与锚点跳转jupyter notebook怎么生成markdown目录语法这个问题答案分两层。第一层手动锚点。Markdown cell 里写[跳转到数据清洗](#数据清洗) ...中间隔很多内容... ## 数据清洗Jupyter 会把标题渲染成 HTML标题文字会生成一个 id规则大致是转小写、空格换成连字符、去掉大部分标点。中文标题一般能直接对应。所以#数据清洗能跳但标题里带英文和数字混排的时候锚点规则容易猜错最可靠的办法是点一下标题链接看浏览器地址栏把#后面那段原样复制过来。第二层自动生成目录。分工具说JupyterLab 内置左侧 TOC 面板View → Table of Contents自动扫描全文标题点一下就跳这是最省事的方案。想在文档里插入一个可点击的目录块装jupyterlab-toc之类扩展或者在第一个 cell 里手写一个 Markdown 列表配上手动锚点。用 nbconvert 导出 HTML 时可以加参数自动生成带目录的页面。顺带说个 Markdown 排版的实操心得标题层级只用#到###。Jupyter 的锚点生成对####及更深的层级支持不稳定而且一个 notebook 里出现五级标题阅读体验本身就不好。内容太细就拆到新 cell 或者拆到新 notebook。如果你还想在正文里插入本地图片、插入数学公式、插入代码块里的语法高亮Markdown cell 都支持。代码块用三个反引号加语言名语法高亮就会生效。这些小细节堆起来notebook 的观感完全不一样。4.3 和 nvim、VS Code 接力干活jupyter notebook nvim这类组合需求说明有人不满足于在浏览器里写代码。可行的路子有这几条路子一Jupytext 双向同步。装pip install jupytext然后把.ipynb和.py配对。配置好之后你在 nvim 或 VS Code 里编辑.py保存时 notebook 自动同步反过来也一样。jupytext --set-formats ipynb,py:percent myfile.ipynb jupytext --sync myfile.ipynbpy:percent格式用# %%分隔单元格vim 里配合 vim-slime 或者 molten 插件可以做到选中一段代码扔给正在运行的 Jupyter 内核执行结果在旁边的窗口显示。这套流程在远程服务器上写代码时特别舒服。路子二让 nvim 直接接入运行中的内核。jupyter console支持--existing参数连到一个已经跑起来的内核jupyter console --existing kernel-abc123.json终端里就能用In [1]:的交互提示符操作同一个命名空间。缺点是输出渲染比较朴素画图看不到。路子三VS Code 原生。这个是成本最低的方案。VS Code 打开.ipynb、装好 Jupyter 扩展、选好内核剩下的和浏览器里几乎一样还能同时用 Git 面板、终端、调试器。vscode python环境配置这个问题的核心其实就三件事选对解释器CtrlShiftP → Python: Select Interpreter、确认python.pythonPath或新版的python.defaultInterpreterPath指向虚拟环境、把虚拟环境的Scripts或bin目录加进终端 PATH。三件事都对90% 的模块找不到问题消失。路子四nvim 里直接开。有jupyter-vim-binding这类插件把浏览器的快捷键映射到 vim不过它的维护状态一般Notebook 7 下基本没戏。真要在终端里写 notebook我更推荐jupytext vim-slime或者干脆 JupyterLab。注意跨编辑器同步.ipynb的时候最容易出问题的就是同一个文件两边同时改。Jupytext 的同步是文件级的冲突了它会报错甚至覆盖。我的做法是同一时间只在一个编辑器里改改完手动jupytext --sync一次别开着自动同步又开着两个窗口。5. 高频故障排查实录5.1 打不开、起不来从终端报错看起jupyter notebook打不开是搜索热度最高的一类问题。排查顺序我总结成一条链先看终端有没有报错 → 再看端口 → 再看浏览器 → 最后看内核。终端没报错浏览器就是不弹。这通常是被--no-browser配置项挡住了或者系统默认浏览器关联坏了。终端里会打印一个形如http://localhost:8888/tree?token...的地址直接复制到浏览器打开。注意那个 token 必须带全漏了会被要求输入密码。终端报端口占用。报错长这样OSError: [Errno 98] Address already in use或者 Windows 上的[Errno 10048]。先看看是谁占着# Linux / macOS lsof -i:8888 # Windows netstat -ano | findstr :8888要么杀掉那个进程要么换个端口jupyter notebook --port 8899。最省事的其实是找到残留的 Jupyter 进程你自己开了两个终端都起了服务第一个没关第二个自然抢不到端口。jupyter命令找不到。Windows 上极常见原因是jupyter.exe装在Python安装目录\Scripts里而这个目录没进 PATH。两种解决办法一是把 Scripts 目录手动加进系统环境变量并重开终端二是绕过命令行直接python -m notebook这个写法不依赖 PATH我一直推荐新手用。首页打得开点开某个 notebook 报错。多半是文件本身的问题JSON 被写坏了、文件太大几百 MB 的 notebook 前端渲染会卡死、路径里有特殊字符。先jupyter nbconvert --to notebook --nbformat 4 问题文件.ipynb试着转一遍能转就说明结构还好转不了就备份后用文本编辑器翻文件尾部。改了配置文件不生效。检查三件事改的是不是当前生效的那份配置jupyter --paths能看到所有配置目录、配置项前缀是不是写成了旧版的NotebookApp、有没有重启服务。配置文件是启动时读一次的改完必须重启。5.2 单元格执行没反应一直在 [*]jupyter notebook单元格执行代码没有任何反应这个现象背后至少有六种不同原因必须分开排查。原因一内核根本没连上。看右上角的圆圈状态空心圆表示空闲实心表示忙如果显示连接失败或者一个感叹号那前端跟内核已经断了。处理方式Kernel 菜单 → Restart Kernel或者直接关掉服务重开。原因二上一个 cell 还在跑。Jupyter 的默认执行模型是串行的同一个内核里同时只能跑一个 cell。前面有个while True或者一个耗时十分钟的训练循环后面所有 cell 提交都排队全都显示[*]。解决办法Interrupt Kernel菜单或按两次I别直接关浏览器——关浏览器杀不掉内核进程。原因三代码里有input()或者需要交互的东西。老版本 notebook 对input()支持很差会一直卡着等输入而输入框根本不显示。新版本好一些但也不可靠。排查办法是回看终端窗口——内核的标准输出和错误默认会同步打印在启动服务的那个终端里那里能看到真实的堆栈和提示。原因四无限循环或者超大计算。这个不用多说看 CPU 占用就知道了。写循环调试的时候习惯性加个计数器或者用tqdm显示进度出问题一眼能看出来。原因五输出量爆炸。比如在循环里print几十万行前端渲染直接卡死表现就是整个页面无响应连菜单都点不动。预防办法调试循环时不要在里面 print用tqdm或者每 1000 次打印一次。已经卡死了就重启服务用编辑器删掉那个 cell 再打开。原因六内核崩了。常见于内存爆掉或者底层库的段错误。终端里会看到Kernel died之类的字样。重启内核然后把代码拆小、分批处理别一次加载几百兆的数据。提示排查没反应最有效的动作是把启动服务的终端窗口留在视野里。Jupyter 的很多错误只在终端显示浏览器里一片安静。我调试内核问题的习惯是两个屏幕一边浏览器一边终端。5.3 ImportError: DLL load failed while importing rpds这个报错近两年问的人特别多值得单独拆开讲。先说它从哪来rpdsrpds-py包是pyrsistent的底层实现之一用 Rust 写的被referencing引用而referencing是jsonschema的依赖jsonschema又是jupyter_events、nbformat等一堆 Jupyter 组件的依赖。所以这条链是jupyter_server → jupyter_events → jsonschema → referencing → rpds-py也就是说这个 DLL 报错跟 Jupyter 本身没直接关系是依赖链底层的一个二进制包在你这台机器上加载失败了。加载失败的原因主要有这几种第一Python 版本和 wheel 不匹配。rpds-py是预编译好的二进制轮子如果你的 Python 版本太新或者太老pip 找不到对应的 wheel 就会去下源码包自己编译。Windows 上编译需要 Rust 工具链绝大多数人没有于是要么编译失败要么编出来一个和当前解释器 ABI 不兼容的东西。诊断命令python -c import sys, platform; print(sys.version); print(platform.architecture()) pip show rpds-py看pip show输出的版本号再去 PyPI 上确认这个版本有没有你当前 Python 版本的 wheel。第二32 位和 64 位的错配。装了一个 32 位的 Python却拉到了 64 位的包这种情况少见但不为零或者系统里有多套 Pythonpython命令指向的和 Jupyter 内核用的不是同一个。第三缺少系统运行库。Windows 上需要对应版本的 Microsoft Visual C 运行库。装过 Visual Studio 或者很多游戏的人一般都有纯净系统上可能缺。这类问题不止影响rpds也会让pyzmq、numpy、cv2等包报类似的 DLL 错误。第四pip 和 conda 混装导致的包版本打架。同一个环境里conda 装的jsonschema配 pip 装的rpds-py版本对不上就可能加载失败。处置顺序我建议这样# 1. 先看看谁依赖它、版本是否对得上 pip check # 2. 强制重装别用缓存 pip install --force-reinstall --no-cache-dir rpds-py # 3. 还是不行的退到有匹配 wheel 的版本区间具体版本看 PyPI 页面对应 Python 版本的标签 pip install rpds-py0.20 # 4. conda 环境里优先用 conda 装 conda install -c conda-forge rpds-py实测最有效的三板斧一是确认 Python 版本别太激进3.11 这种主流版本上 wheel 覆盖最全二是--force-reinstall --no-cache-dir清掉可能损坏的旧文件三是把整个环境重建一遍——虚拟环境删掉重装比在坏环境里修半天快。注意如果你在 CMD 里装了包但 Jupyter 内核用的是另一个 Python那怎么修都没用。先跑import sys; print(sys.executable)在 notebook 里确认解释器路径再看这个路径下有没有那个包。这一步能排除掉一大半假故障。同类问题还有ImportError: DLL load failed while importing _ssl缺 OpenSSL 相关库、while importing qtPyQt 环境错乱、cv2装不上或导入失败多半是 OpenCV 的轮子和 numpy 版本或 Python 版本不匹配建议指定版本区间安装。排查思路是统一的确认解释器路径 → 确认包版本和 Python 版本匹配 → 确认架构一致 → 强制重装或重建环境。5.4 内核找不回、画图不出结果和其它杂症内核列表里出现Python 3 (ipykernel)但点了报错。这个内核指向的解释器路径已经不存在了环境被删、目录被移动。jupyter kernelspec list找到路径jupyter kernelspec remove 名字删掉再重新注册。notebook 里import pandas成功import 自己写的模块失败。根因是当前工作目录不在sys.path里了。老版本 notebook 默认会把 notebook 所在目录加进sys.path新版本或某些配置下不一定。稳妥做法是在 notebook 开头加import sys, os sys.path.insert(0, os.path.abspath(..))或者把项目做成可安装的包pip install -e .一劳永逸。matplotlib 画图不出图只显示Figure size ...。加%matplotlib inline如果用了fig, ax的写法确认最后调用了plt.show()或者把fig单独放在 cell 最后一行。横坐标标签太密集糊成一团。这是python画图横坐标太密集的经典问题几个办法按效果排序import matplotlib.pyplot as plt from matplotlib.ticker import MaxNLocator fig, ax plt.subplots(figsize(12, 4)) ax.plot(x, y) # 方案一标签旋转 ax.tick_params(axisx, rotation45) # 方案二限制刻度数量 ax.xaxis.set_major_locator(MaxNLocator(nbins10)) # 方案三日期轴自动格式化 fig.autofmt_xdate() # 方案四加大画布尺寸减少纵向挤压 plt.tight_layout() plt.show()实际组合使用效果最好先figsize给足宽度再限制刻度数量最后旋转标签。顺序反了容易白调。图里中文显示成方块。指定中文字体plt.rcParams[font.sans-serif] [SimHei] # Windows # plt.rcParams[font.sans-serif] [Arial Unicode MS] # macOS plt.rcParams[axes.unicode_minus] Falsenotebook 里的输出越堆越多、滚动卡顿。用 Cell → All Output → Clear 清一遍或者存文件前用nbstripout把输出全部剥掉。5.5 常见问题速查表现象最可能的原因第一步动作命令找不到jupyterScripts 目录不在 PATH改用python -m notebook提示端口被占用有残留服务进程换端口或lsof -i:8888排查浏览器不弹出配置了--no-browser复制终端里的地址手动打开单元格一直[*]前一个 cell 没跑完 / 内核卡死Interrupt Kernel看终端输出整个页面无响应输出量太大重启服务删掉爆输出的 cellModuleNotFoundError内核选错了解释器在 cell 里打印sys.executableDLL load failed二进制包版本或架构不匹配pip check 强制重装内核重启后变量消失正常行为不是 bug用%store或存文件持久化导入本地模块失败工作目录不在sys.pathsys.path.insert(0, ...)中文乱码没指定中文字体设置font.sans-serif6. 从草稿纸到可交付notebook 的工程化收尾6.1 目录组织与依赖冻结notebook 天生容易长成一堆散落在下载目录里的Untitled1.ipynb。我现在的目录结构大概是这样project/ ├── data/ # 原始数据只读 ├── notebooks/ # 探索用 notebook编号排列 │ ├── 01-explore.ipynb │ └── 02-model.ipynb ├── src/ # 稳定下来的函数抽取到这里 │ └── feature.py ├── outputs/ # 导出的图表和报告 ├── requirements.txt └── README.md两个细节决定这套结构能不能坚持下来。第一notebook 一律用编号前缀01-、02-文件管理器里自然按时间顺序排比按名字排强。第二src/里的模块要用%autoreload加载改动即时生效这样你才有动力把重复代码抽出去而不是一直复制粘贴。依赖冻结这一步千万别省pip freeze requirements.txt换机器、隔了三个月回来跑pip install -r requirements.txt就能复现环境。但要注意pip freeze会把你环境里所有包都写进去包括临时装来试的。干净的做法是在虚拟环境里只装项目必需的包或者在文件里手动维护一个精简列表。conda 环境用conda env export --no-builds environment.yml。6.2 自动执行与报告导出notebook 真正发挥威力是在一键跑完并出报告这件事上。nbconvert是内置的工具# 导出 HTML并且先重新执行一遍确保结果是最新的 jupyter nbconvert --to html --execute notebooks/02-model.ipynb --output-dir outputs/ # 导出 Markdown方便贴进文档系统 jupyter nbconvert --to markdown notebooks/02-model.ipynb # 导出成 Python 脚本做代码审查用 jupyter nbconvert --to script notebooks/02-model.ipynb--execute这个参数是关键。它保证导出的是真实执行过的最新结果而不是文件里陈旧的缓存输出。做定期报表的场景里把这个命令挂到系统的定时任务上notebook 就变成了一个会自动更新的报告生成器。需要传参数跑不同数据集的时候用papermillpip install papermill papermill notebooks/02-model.ipynb outputs/run-2024.ipynb -p date 2024-01-01在 notebook 里用一个标记了parameters的 cell 声明参数名papermill 会在执行时注入。这一套在批量跑实验的时候非常好用。最后是版本控制的老问题。.ipynb的 JSON 里塞满了输出和执行计数两个人改同一个小地方Git diff 能出来几千行。解决办法是装nbstripout提交前自动剥掉输出pip install nbstripout nbstripout --install # 在当前仓库装 git filter剥掉输出的 notebook 只留代码和 Markdowndiff 清爽得多。代价是别人 clone 下来看到的是没有结果的版本得自己跑一遍。团队里如果很在意结果快照那就保留输出改用大文件存储或者干脆导出 HTML 一起提交。6.3 我个人坚持的几个习惯写到这里讲几个我用了几年之后固化下来的习惯都是被坑出来的。第一个每个 notebook 的第一行永远是 Markdown 标题加一句话说明。写上这是干什么的、数据从哪来、跑一遍大概多久。三个月后的你会感谢现在的你。第二个不在 notebook 里写超过 30 行的函数。抽到.py里去用%autoreload加载。notebook 里的长函数没法单元测试改一次跑一次效率极低。第三个交付前一定 Restart Run All。我见过太多次本机跑得好好的、别人打开全是NameError的场面根因都是依赖了历史变量。这一个动作能挡掉 80% 的交付事故。第四个大计算的结果及时落盘。训练了二十分钟的模型跑完立刻joblib.dump或者to_parquet存下来别让它只活在内核内存里。内核一崩二十分钟白费。我踩过这个坑至今记得那个下午。第五个调试循环不要在循环体内 print。用tqdm显示进度或者每千次打一行。这条规则帮我省下的时间比任何优化技巧都多。第六个别信我待会儿再整理。notebook 一旦变成垃圾场就很难收拾。每做完一个阶段就顺手清掉失败的实验 cell、删掉没用的变量、把结论写成 Markdown。一个能给人看的 notebook价值比十个自己都看不懂的草稿高得多。最后分享一个小技巧收尾如果你的 notebook 里有一段代码要反复跑、但每次只改一两个参数把它写成函数然后上面加一个 cell 用interact装饰器配ipywidgets就能得到一个带滑块和输入框的小控制面板from ipywidgets import interact interact(n(1, 50), scale(0.1, 2.0, 0.1)) def demo(n10, scale1.0): print([round(i * scale, 2) for i in range(n)])拖一下滑块结果就刷新调参效率比来回改代码高一个数量级。这个小东西我第一次用的时候感觉像给 notebook 装上了仪表盘。