Jupyter Notebook 如果只被当成一个能写代码的记事本就浪费了它一半的价值。它真正的用法是把代码、数据、图表、说明文字和运行结果放在同一份文档里让分析过程可以逐段回放、逐段检查、逐段复用。NTMSS2023 第 4 天第 1 节的内容是 “Intro to Jupyter notebooks”正好是这套工具的入门入口。这篇教程会按照实际使用的顺序来写先看 Jupyter 能做什么、大概需要什么环境然后走一遍安装、启动、新建、运行、导出、批量执行的完整流程。最后把最容易踩的坑集中列出来方便你遇到问题时直接对照排查。无论你是刚接触 Python 数据分析还是想在团队里统一分析流程这篇文章都可以直接作为第一份操作手册。1. Jupyter Notebook 核心能力速览Jupyter Notebook 严格来说不是单一的软件而是一套组件组合浏览器里的交互式界面、独立运行的计算内核、文件格式 .ipynb、以及周边导出和调度工具。这套结构决定了它的能力边界。能力项说明项目类型交互式计算环境常用于数据分析、教学、算法原型验证主要组成Notebook 界面、Kernel 内核、.ipynb 文件格式、nbconvert、JupyterLab支持语言通过安装不同内核支持 Python、R、Julia 等最常见的是 Python启动方式命令行启动 JupyterLab 或 Notebook浏览器访问远程访问默认只监听本机可配置远程访问但需要额外处理安全认证批量任务可用 nbconvert --execute 或 papermill 批量执行笔记本接口能力提供 REST API也支持 Notebook 文件格式级调用交互能力支持 Markdown 单元格、代码单元格、表格、图片、交互式控件适合场景数据探索、课程教学、实验记录、论文复现、算法调试不适合场景大型工程开发、高并发服务、需要长期运行的独立任务从这张表可以看出来Jupyter 的强项不是“部署一个服务”而是“让一个分析过程可读、可改、可重跑”。后面所有操作都围绕这个核心展开。2. 适用场景与使用边界先回答最实际的问题我要不要用 Jupyter用它解决什么问题最典型的适用场景是数据探索。拿到一批数据不想一开始就写完整脚本而是想快速看看字段、分布、缺失值这时候 Jupyter 的逐格运行优势非常明显写一小段、跑一小段、立刻看结果发现不对就改。对课程教学来说它可以把理论、公式、示意代码和效果图并排放在一起学生可以自己动手改参数重跑。对论文复现来说notebook 文件天然记录了运行顺序和中间输出比零散的 .py 文件更容易还原当时的分析过程。它不适合什么场景如果任务是一个完整的后端服务比如 Web API、爬虫调度器、消息队列消费者那不应该用 notebook 长期运行因为 kernel 断开会话就丢也不方便做进程守护。如果代码库很大、模块很多、需要严格测试和类型检查Jupyter 也不是最合适的主战场它更适合做研究阶段的原型工程化阶段仍然建议把稳定代码抽成 .py 模块和测试用例。还有一个必须强调的使用边界Jupyter 里运行代码时单元格之间是共享全部变量的这带来便利也带来隐患。前一个单元格定义了变量后一个单元格可能隐式依赖它重跑整个 notebook 时顺序一乱结果就变样。所以要养成“从头到尾重跑一遍”的验证习惯。涉及敏感数据时不要把明文密钥、手机号、身份证号、业务隐私数据直接放在 notebook 里也不要随手把带敏感输出的 notebook 分享出去。本地演示用测试数据线上数据要脱敏后再进 notebook。3. 环境准备与前置条件Jupyter 的本质是一个 Python 包加浏览器界面环境准备并不复杂但要避免后面反复折腾依赖冲突所以环境隔离这一步不能省。3.1 操作系统的选择Jupyter Notebook 官方支持 Windows、macOS 和主流 Linux 发行版。Windows 上安装时要注意如果路径中含中文或空格可能带来一些兼容问题建议所有安装目录尽量用英文路径。Linux 服务器上安装时注意区分系统自带的 Python 和通过包管理器安装的 Python避免混用不同版本。3.2 Python 版本与虚拟环境检查运行以下命令确认当前 Python 版本python --version pip --version如果还没有 Python推荐先安装 Miniconda体积比 Anaconda 小很多但足够管理虚拟环境。使用 conda 或 venv 创建独立环境不要让 Jupyter 直接装在系统 Python 里。使用 conda 创建环境conda create -n jupyter-env python3.11 -y conda activate jupyter-env如果系统里只有普通 Python可以用 venv 创建虚拟环境python -m venv jupyter-env # Windows: jupyter-env\Scripts\activate # Linux/macOS: source jupyter-env/bin/activate3.3 磁盘空间与依赖规划Jupyter 本体占用空间很小但安装数据分析常用库比如 pandas、numpy、matplotlib会占用几百 MB 到 1GB 以上。在服务器上使用时要提前给用户目录和临时目录留出空间。.ipynb 文件本身是 JSON 格式如果单元格里嵌入了大量图片、大表格输出文件会迅速膨胀所以要注意保存前清理不必要的输出。4. 安装部署与启动方式环境准备好之后安装和启动 Jupyter 只需要几条命令。这里推荐安装 JupyterLab它是新版 Notebook 的功能超集既有传统 Notebook 的文件列表又支持多标签页、插件、终端、代码格式化等扩展功能。4.1 安装 JupyterLabpip install jupyterlab安装完成后确认版本jupyter lab --version如果是在服务器或容器中运行也可以考虑安装完整的数据科学基础包pip install pandas numpy matplotlib4.2 本地启动服务默认情况下JupyterLab 只绑定在 127.0.0.1也就是只有本机能访问这个默认策略比较安全建议保持。启动命令如下jupyter lab启动后终端会输出一个带 token 的访问地址形如http://127.0.0.1:8888/lab?token一串随机字符浏览器打开这个地址就可以进入工作台。如果你想手动指定端口比如端口 8889 被占用时jupyter lab --port 8889如果想指定监听地址和端口比如在远程服务器上使用需要显式设置jupyter lab --ip 0.0.0.0 --port 8888 --no-browser这里必须提醒将 IP 设置为 0.0.0.0 意味着同一网络内其他机器都可以访问你的服务没有设置密码时非常危险。远程使用时要先配置密码或使用 token并且建议配合防火墙只放行可信 IP。不要把未保护的 Jupyter 暴露到公网。4.3 设置登录密码设置密码可以避免每次复制 tokenjupyter server password输入两次密码后后续访问到登录页输入该密码即可。这个密码会写入配置文件中权限需要由当前用户控制。4.4 利用 JupyterLab 的桌面入口如果是个人电脑日常使用JupyterLab 安装后通常会在开始菜单或应用程序目录中生成快捷方式直接双击启动即可。启动后浏览器会打开工作台界面左侧是文件树中间是文件编辑区。界面语言为英文但源码和 Markdown 支持中文编辑。5. 功能测试与效果验证安装完成只是一个开始接下来要验证 notebook 是否真的能run起来。下面按“新建—运行—导出”的主线走一遍。5.1 新建第一个 Notebook进入 JupyterLab 工作台后点击左侧号在 Launcher 中找到 Python 3 图标点击即可新建一个 notebook。注意这里的 Python 3 代表当前环境里的默认 kernel。如果你是在 conda 环境里安装的 jupyter但 Launcher 里没有显示这个环境的 Python说明 kernel 没有注册需要安装 ipykernelpip install ipykernel python -m ipykernel install --user --name jupyter-env --display-name Python (jupyter-env)注册完成后刷新浏览器页面Launcher 里就会多一个对应的选项。5.2 单元格基本运行Notebook 由两种单元格组成Code 单元格和 Markdown 单元格。Code 单元格用于运行程序按Shift Enter执行并跳到下一个单元格Markdown 单元格用于写说明文字同样按Shift Enter渲染。先在第一个 Code 单元格里写一个最简单的测试print(Hello Jupyter)按Shift Enter执行输出区域应显示Hello Jupyter。接着测试一下基本的 Python 操作data [1, 2, 3, 4, 5] mean sum(data) / len(data) print(fmean: {mean})此时说明 kernel 正常工作。注意变量data和mean已经存进了当前 kernel 的全局命名空间在后续任意单元格中都可以直接引用。5.3 Markdown 单元格与图文混排在当前单元格上方点击 “” 插入一个新单元格切换单元格类型为 Markdown输入# 数据分析实验记录 - 数据来源示例数据 - 分析目标验证均值计算 - 环境JupyterLab Python 3按Shift Enter渲染文档会显示标题和列表。这就是 notebook 比普通脚本直观的原因代码、输出、笔记在同一个文件里按顺序排列。5.4 可视化验证数据分析和展示是 Jupyter 的标准功能。先安装 matplotlib然后运行import matplotlib.pyplot as plt plt.plot([1, 2, 3, 4], [2, 4, 1, 3]) plt.title(Test Plot) plt.show()输出区域应显示折线图。如果图片能正常显示说明 matplotlib 集成没问题。需要说明的是在 notebook 中通常不需要显式调用%matplotlib inline新版 JupyterLab 默认就能嵌入图片但如果是旧版本 Notebook可能需要手动设置。5.5 时间开销测试分析场景里经常需要关心一段代码跑多久。用魔术命令%time或者%%time可以不额外写代码完成计时%%time total 0 for i in range(1000000): total i print(total)计时结果会显示在单元格输出中比如CPU times: user 62.3 ms, sys: 3.1 ms, total: 65.4 ms Wall time: 65.9 ms这个能力在排查性能问题时很实用。%time只对单条语句计时%%time对当前单元格整体计时。5.6 重新执行整个 NotebookNotebook 的一个常见坑是你只从上到下执行一次没问题但修改中间某个单元格后后面单元格里的变量可能就变了。所以每次改动后最好通过菜单Run Run All Cells重跑整个 notebook验证逻辑是否仍然正确。这个操作在正式分享或提交输出前很有必要。5.7 保存与导出notebook 的自动保存默认开启但建议长会话中手动按CtrlS保存。导出为其他格式使用菜单File Save and Export Notebook As可以导出为 Markdown、HTML、Python 脚本等。命令行导出在后面接口部分讲批量场景更常用。6. 接口 API 与批量任务很多人只把 Jupyter 当个人工具用忽略了一个亮点它的文件格式和执行逻辑是可以被程序调用的。这意味着你可以批量执行若干 notebook、批量导出报告甚至把 notebook 当成一种可复现的“分析脚本”。6.1 命令行批量转换nbconvertnbconvert 是 Jupyter 自带的转换工具。把一个 notebook 转为 HTML 报告jupyter nbconvert --to html analysis.ipynb转为 Markdownjupyter nbconvert --to markdown analysis.ipynb这个命令可以加--execute参数先执行所有单元格再导出jupyter nbconvert --to html --execute analysis.ipynb加上--ExecutePreprocessor.timeout600可以加大超时时间适合长时间运行的单元格jupyter nbconvert --to html --execute analysis.ipynb --ExecutePreprocessor.timeout600批量转换多个 notebook 时可以直接把多个文件名放一起或者写一个简单的 shell 循环。例如在 Linux/macOS 下for file in notebooks/*.ipynb; do jupyter nbconvert --to html --execute $file doneWindows PowerShell 下可以写Get-ChildItem notebooks\*.ipynb | ForEach-Object { jupyter nbconvert --to html --execute $_.FullName }这种方式的优势是简单每个 notebook 独立执行失败时该文件会报错但不会影响其他文件。6.2 参数化批量执行papermill如果 notebook 里跑的是同一套分析逻辑只是输入参数不同nbconvert 的缺点就暴露了每次都要手动改单元格里的变量。paper mill 是专门解决这个问题的工具通过在 notebook 中标记参数单元格让外部命令注入参数然后批量执行并单独保存输出。安装 papermillpip install papermill假设 notebook 中某个 Code 单元格是# 参数 input_file data/input.csv threshold 0.5用 papermill 执行并注入新参数papermill analysis.ipynb output/analysis_0.8.ipynb -p threshold 0.8 -p input_file data/input_2.csv它会把参数单元格替换为指定值然后从头执行整个 notebook并把结果输出到新文件。这样可以一次跑多个参数组合papermill analysis.ipynb output/analysis_0.1.ipynb -p threshold 0.1 papermill analysis.ipynb output/analysis_0.5.ipynb -p threshold 0.5 papermill analysis.ipynb output/analysis_0.9.ipynb -p threshold 0.9执行完成后output 目录下会保留每个参数组合对应的完整 notebook附带全部运行输出。这对参数扫描、敏感性分析、周期报表自动化非常有帮助。6.3 使用 Jupyter REST APIJupyter 服务本身也提供 HTTP 接口比如查看当前运行的内核、创建内核、执行代码等。默认访问需要 token可以在启动日志里找到。向内核执行代码需要先获取 kernel id然后通过 WebSocket 发送消息这个过程比较复杂。相对实用的场景是列出服务状态和 kernel 列表。列出 kernel 列表curl -H Authorization: token 你的token http://127.0.0.1:8888/api/kernels返回结果是一个 JSON 数组包含 name、kernel id、connections 等信息。用 Requests 也可以import requests url http://127.0.0.1:8888/api/kernels r requests.get(url, headers{Authorization: token 你的token}) print(r.json())如果你的主要诉求是“让程序运行某个 notebook 并拿到结果”更推荐 nbconvert 或 papermill而不是直接调 API。直接调 REST API 适合做集成监控、自动化运维比如确认某个服务节点上的 kernel 还活着。6.4 任务队列与失败重试建议批量执行 notebook 时要考虑稳定性。建议每次执行都在独立输出目录中保存结果文件避免覆盖原文件。执行日志要保留哪个文件失败、哪一步超时要有记录。对于临时失败比如网络下载依赖导致的失败可以加一层重试先执行一次失败后等几秒再执行一次。对于参数类任务强烈建议把参数文件集中管理用 JSON 或 YAML 记录参数组合方便复现{ task1: { input_file: data/input_1.csv, threshold: 0.5 }, task2: { input_file: data/input_2.csv, threshold: 0.8 } }然后写一个 Python 脚本读取 JSON 后调用 papermill 接口逐个执行。7. 资源占用与性能观察Jupyter 不是重型应用但它的资源占用情况会直接决定你的工作流是否顺畅。核心要观察两个维度内存占用和 kernel 占用。7.1 内存占用Jupyter 启动后Node.js 前端进程和一个 Python kernel 进程会常驻。前端进程负责浏览器界面和文件服务kernel 进程负责执行代码。内存占用不像固定指标取决于你加载了多少数据、多少库。比如一个空 notebook 的 kernel 内存占用很低但一旦加载大 DataFrame内存会明显上升。所以不要用“一个 kernel 占多少内存”来量化而要把top或任务管理器里的 python 进程当作观察点。在 Linux 服务器上可以用top -u $USER或者用 htop 实时看htop如果页面卡顿通常不是 Jupyter 本身的问题而是 kernel 正在执行大计算。此时浏览器请求等结果并不代表 Jupyter 卡死。7.2 内核数量与端口每新建一个 notebookJupyter 会对应一个 kernel 进程。打开的 notebook 越多后台进程就越多。长时间不用的 notebook 应该关闭并关闭其 kernel否则会白占内存。可以通过菜单File Shut Down Kernel关闭指定 notebook 的内核也可以通过左侧Running Terminals and Kernels面板统一管理。7.3 降低资源占用的实用方法不要在同一个 notebook 里加载多份大型数据集用不到的就释放或删除。大矩阵和中间结果变量要及时释放del 变量名之后如果内存没有立即下降可以调用import gc; gc.collect()。涉及长时间循环时优先用向量化写法比如把 Python 循环改写为 pandas 或 numpy 操作。带图像的单元格会被缓存到内存中输出过多时重启 kernel 会更干净。如果是为了保留运行结果而保存 large output可以在保存前清空输出再重跑一遍生成最终报告。8. 常见问题与排查方法问题现象可能原因排查方式解决方案浏览器打开地址后提示 404服务未启动或地址端口写错检查终端日志中的访问 URL确认端口重新用jupyter lab启动复制终端里的完整 URL启动后找不到 token服务启动时没有打印 URL或终端滚动丢失执行jupyter server list查看当前服务和 token也可用jupyter server password设置固定密码端口被占用另一个 Jupyter 服务或程序占用了 8888netstat -anofindstr 8888Windows或lsof -i:8888macOS/Linux新建 notebook 时没有 Python 3 kernel当前环境没有注册 ipykernel运行jupyter kernelspec list查看已注册内核执行python -m ipykernel install --user --name 环境名单元格执行后提示 ModuleNotFoundError模块没有安装或安装到了另外的 Python 环境在 notebook 里执行import sys; print(sys.executable)确认 kernel 使用的 Python 路径在对应环境中执行pip install 包名代码能跑但页面不显示图片matplotlib 输出嵌入配置问题检查图表代码是否在正确单元格是否有plt.show()新版本一般自动嵌入旧版本可添加%matplotlib inlinenotebook 文件保存失败权限不足或磁盘空间不足查看终端日志检查目录写权限更换输出目录或调整用户权限远程访问被拒绝服务只监听 127.0.0.1或防火墙拦截检查启动命令是否有--ip 0.0.0.0检查防火墙规则明确设置监听地址配置密码并放行端口批量执行时某个文件卡住单元格中有长循环或等待超时增加 ExecutePreprocessor timeout--ExecutePreprocessor.timeout600长时间运行后页面无响应kernel 内存过大或正在计算查看系统资源占用查看终端日志重启 kernel减少单次计算量9. 最佳实践与使用建议Jupyter 用久了很多人会发现最影响效率的不是功能不会用而是 notebook 结构混乱、难以复现。下面几条实践建议适合个人和团队场景。第一一个 notebook 只解决一个分析问题。不要把数据清洗、特征工程、建模、绘图、导出报告全塞进同一个文件。按阶段拆成多个 notebook比如01_load_data.ipynb、02_clean_data.ipynb、03_model.ipynb每个文件专注一个环节后续调用和回溯都方便。第二单元格的顺序就是执行逻辑的顺序。从上到下写完每次修改后都完整重跑一次。不要在 notebook 中间随机跳着执行否则输出的结果只能代表当前顺序下的状态不是可复现的结果。分享前用Run All Cells重跑一遍确认所有输出都能复现。第三控制单元格粒度。一个单元格里写几千行代码和写一个 .py 脚本没区别。合理粒度是每个单元格完成一个独立子任务函数定义、参数设置、数据加载、可视化、结果统计分别放在不同单元格。这样别人阅读时可以按段理解逻辑。第四敏感信息不要留在 notebook 里。数据库密码、API Key、个人数据等不应该写入代码单元格或输出区域。如果必须做配置用环境变量或单独的配置文件并在提交前清理输出。第五版本控制要同步。.ipynb 是 JSON 格式直接放进 Git 会导致 diff 难读而且输出变化会造成大量无关改动。团队协作时可以把最终版本导出为 .py 或 Markdown 审查也可以在 Git 中配置清理工具过滤输出。如果只是自己使用至少要做到模型文件、输入数据、输出结果分别放在独立目录中notebook 文件按日期或版本命名。第六依赖环境要记录。在项目根目录维护 requirements.txt 或 environment.yml。这样换机器或换环境时一条命令就能恢复依赖pip freeze requirements.txt # 或 conda env export environment.yml恢复环境pip install -r requirements.txt # 或 conda env create -f environment.yml第七批量执行时先小范围测试。第一次用 papermill 批量跑 20 个参数组合前先跑 1 个验证 notebook 能正常执行、输出路径正确。确认没问题后再扩大到全部参数。批量任务要保留日志以便定位哪个参数组合执行失败。第八注意远程服务的访问边界。如果是在服务器上用 Jupyter建议启用密码认证、只监听可信 IP、通过 SSH 隧道访问而不是直接暴露公网。从安全稳定角度考虑公共服务部署不应该依赖 notebook 长期进程。10. 总结与下一步Jupyter Notebook 最值得尝试的点是把“写代码”和“写分析文档”合并成同一件事。你可以在一个 .ipynb 文件里同时保留思路、代码、图表和结论而且随时可以重新执行。最开始拿到一个 notebook 时先跑一遍Run All Cells再逐段修改学习理解每个单元格做了什么是上手最快的方式。最容易踩的坑有两个第一环境混乱模块装到了别的 Python 环境导致启动后找不到包第二单元格执行顺序混乱导致最终结果无法复现。只要把虚拟环境和“重跑全部”这两个习惯养成大部分 Jupyter 使用问题都能规避。下一步可以按自己的方向继续扩展学习 JupyterLab 的快捷键和分屏操作提升日常编辑效率。研究 papermill 与参数化执行把你的 notebook 变成可批量执行的自动分析流程。尝试 Jupyter Book把多个 notebook 组织成在线阅读文档。在云端平台里使用 Jupyter比如通过 Binder 快速分享教学示例或使用云端 GPU 跑模型实验。将稳定代码从 notebook 中抽成 .py 模块再通过 notebook 做调用演示兼顾工程化和可读性。Jupyter 的关键不是某个花哨功能而是让你的分析过程可以被记录、被解释、被复用。从这节课的内容出发先跑通一个最小示例再逐步加入你要处理的数据和方法就是最稳的前进路径。