Jupyter Notebook 是目前 Python 数据分析、机器学习教学和快速原型验证里最常用的交互式编程工具。它最大的特点是把代码拆成一个一个单元格每个单元格可以单独运行运行完立刻在当前页面看到结果包括表格、图片、提示信息。这种“边写边跑、边跑边看”的工作方式比传统写完整个脚本再运行要直观很多尤其是需要反复调整参数、观察中间结果、一边写代码一边解释逻辑的场景。如果你之前只写过.py脚本第一次打开 Jupyter Notebook 多半会不习惯文件不再是单纯的从上到下执行脚本而是一个带单元格和运行状态的文档。你需要重新理解运行顺序、代码状态、保存方式和环境依赖。这些问题不搞清楚后面很容易遇到“刚才还能跑现在到处都是红色报错”的情况。这篇文章会按实际使用顺序把 Jupyter Notebook 的安装、启动、单元格操作、内核概念、常见问题以及和 JupyterLab、PyCharm 的选型区别完整过一遍。内容尽量照顾刚入门的读者也会保留一些给有经验读者参考的判断细节。1. 先搞清楚 Jupyter Notebook 到底解决什么问题1.1 交互式编程和“写完整脚本再运行”的区别传统开发方式通常是这样打开 IDE写一个main.py写完之后点击运行程序从头跑到尾最后在控制台里看到输出。如果中间某个变量结果不是预期值改代码重新运行再从头看一遍。这种模式适合逻辑完整、流程固定的工程任务但在数据探索和教学演示中会显得很笨重。Jupyter Notebook 把工作单元从“整个文件”缩小到“一个单元格”。你可以先写第一段代码读取数据运行它立刻看到前几行再写第二段代码做数据清洗运行看清洗结果再写第三段画图。每一步的输出都和代码紧挨着放在同一个文档里。如果中间发现某一列的格式不对不需要重跑整个流程只需要修改对应单元格再运行一次。这里的核心是“状态保持”。Notebook 中的一个单元格运行完成后变量会保留在同一个内核里。后面的单元格可以直接使用前面的变量不需要重新导入数据、重新初始化模型。这和脚本文件每次从头执行一遍的逻辑完全不同。1.2 适合什么场景不适合什么场景我个人的判断是Jupyter Notebook 最适合以下三种场景。一是数据分析探索。原始数据什么样、缺失值有多严重、某个字段怎么分布这些都需要反复查看、画图、尝试不同的处理方式。Notebook 的逐格运行模式非常匹配这个工作流。二是教学和分享。代码和解释文字能放在同一个文档里输出直接保留在代码下方读者打开文件就能看到完整过程和结果不需要自己重新跑一遍。三是算法原型验证。写一个模型训练脚本时先在小数据集上验证思路一个单元格一个模块地测试比整体脚本调试效率高。但它也有明显不适合的场景。大型软件工程、长时间后台任务、高度依赖模块拆分和自动化测试的项目不适合用 Notebook 作为主开发环境。原因也很直接执行顺序靠手动控制测试和部署很难标准化文件本身也不方便做代码审查。1.3 核心概念单元格、内核、会话刚开始接触 Jupyter Notebook必须先理解三个词。单元格Cell是文档的基本组成单位。它可以是代码也可以是 Markdown 文本。代码单元格会执行代码Markdown 单元格会渲染成带格式的文档文字。内核Kernel是真正执行代码的 Python 解释器。Notebook 界面本身只负责编辑和展示代码实际运行在一个后台进程中。每次启动一个 Notebook它都会连接到一个内核。如果内核崩了界面还在但运行代码会报错。会话Session指的是从打开 Notebook 到关闭之间的持续连接状态。会话期间内核里的变量和模块状态一直在。理解这三个概念之后绝大多数操作就都能归类了新建单元格是在编辑文档启动或重启内核是在管理系统状态保存文件是把当前文档写到磁盘。2. 安装方式怎么选Anaconda 还是 pip2.1 新手优先考虑 Anaconda 的理由安装 Jupyter Notebook新手最稳的方式是安装 Anaconda。Anaconda 是一个 Python 发行版它自带 Python、Jupyter Notebook、JupyterLab以及数据科学领域常用的一大批第三方库比如 NumPy、Pandas、Matplotlib、Scikit-learn。这意味着你不需要先装 Python再装 pip再逐个装依赖才能开始写代码。对 Windows 用户来说这个优势尤其明显很多本地环境问题都是因为 Python 和系统环境变量配置不正确导致的。Anaconda 安装完成后桌面会多一个 Anaconda Navigator。这是一个可视化入口你可以在里面直接启动 Jupyter Notebook也可以启动 JupyterLab还能查看当前安装了哪些环境、哪些包。对于不熟悉命令行的人来说这是最不容易出错的启动方式。不过 Anaconda 也有缺点安装包大启动速度也不快。如果你已经有比较干净的 Python 环境并且手头所有依赖都能通过 pip 正常安装那直接装 Jupyter 就够用不一定非要装 Anaconda。2.2 已经有 Python 环境时用 pip 安装如果你已经有 Python 3.8 以上版本并且确认pip命令可用可以直接执行pip install jupyter安装完成之后验证一下jupyter notebook --version能输出版本号说明安装成功。我这里建议用虚拟环境不要直接在系统级 Python 环境里装。Jupyter 的依赖数量并不少和系统级环境里的包一旦产生冲突排查起来很费时间。创建虚拟环境并安装 Jupyter 的大概流程是python -m venv myenv # Windows myenv\Scripts\activate # macOS / Linux source myenv/bin/activate pip install jupyter在虚拟环境里装好之后启动 Jupyter再在 Notebook 里新建一个 Python 3 内核用的就是当前虚拟环境的解释器和依赖。这一点非常关键很多初学者在这里踩坑明明在终端里pip install pandas成功了结果打开 Notebook 运行import pandas还是报错。原因就是 Notebook 使用的不是当前终端环境而是系统环境或者其他虚拟环境。2.3 启动方式终端命令、Anaconda Navigator、快捷方式Jupyter Notebook 的启动方式有很多种但本质上都是启动一个本地服务。在终端里执行jupyter notebook默认会在http://localhost:8888或127.0.0.1:8888打开一个文件管理页面。如果使用 Anaconda打开 Anaconda Navigator找到 Jupyter Notebook 栏点击 Launch 也可以。这两种方式没有本质区别Anaconda Navigator 只是帮你省去了在终端里输入命令这一步。需要注意一个细节不管哪种方式启动那个终端窗口都不能关闭。Jupyter 的本地服务进程就运行在终端里关闭窗口等于停止服务。页面返回“连接断开”或者新打开时找不到服务通常就是这个原因。如果你在 Windows 上安装的是 Anaconda还可以通过开始菜单里的 “Jupyter Notebook” 快捷方式启动。这个快捷方式本质上也是执行启动命令只不过它在启动时会把当前工作目录设置到用户目录。文件保存位置最终会落在当前启动目录下所以建议在启动前先想清楚项目文件放在哪里。3. 第一次打开 Notebook四个操作先跑通3.1 新建、改名、保存打开 Jupyter 主页面后右边是一个文件列表。点击页面右上角的 New选择 Python 3就能新建一个 Notebook 文件。新建之后默认文件名是 Untitled.ipynb点击文件名区域可以重命名。Notebook 文件的后缀是.ipynb它的内容结构很特殊。用记事本打开会看到一堆 JSON 结构里面保存了单元格内容、输出结果、执行顺序等元信息。这个格式适合 Jupyter 自己读写但不适合直接手工编辑也不适合放在 git 里做严格对比。保存操作默认快捷键是CtrlSmacOS 上是CmdS。除了手动保存Jupyter 还有一个自动保存机制默认每隔一段时间保存一次检查点。检查点的作用是给你一个恢复机会如果改乱了可以通过 File 菜单里的 Revert to Checkpoint 回到之前的保存状态。平时用不到但在做了大量破坏性修改后发现想回退时会很有用。3.2 Code 单元格和 Markdown 单元格Notebook 里有两类最重要的单元格Code 和 Markdown。Code 单元格存放代码。它是默认类型也是每个 Notebook 里真正执行计算的部分。输入print(hello)按ShiftEnter运行下方会立刻显示输出hello。Markdown 单元格存放带格式的说明文字。它不会被执行而是被渲染成类似网页的排版效果。你可以写一级标题、二级标题可以用**加粗**可以用-列列表也可以写简单的数学公式。教学型 Notebook 通常会交替使用 Markdown 单元格和 Code 单元格先用文字说明“我要做什么、为什么这么做”下面再放一段代码演示。切换单元格类型有两种方式一种是选中单元格后在顶部工具栏的下拉菜单里改另一种是使用快捷键M把当前单元格切换为 Markdown按Y切回 Code。初学者经常忘记切换结果把说明文字写进了 Code 单元格运行时冒出SyntaxError。看到这种报错第一反应应该是检查单元格类型。3.3 运行顺序由你自己控制不是从上到下和普通脚本不同Jupyter Notebook 不会强制按单元格从上到下执行。你可以先运行第三个单元格再运行第一个单元格。每个单元格左侧的In [数字]会记录这个单元格被第几次执行。这个设计是优点也是坑点。优点是你可以只修改某一步逻辑然后单独重跑那一步不用整个文档从头再来。坑点是如果单元格之间存在依赖而你运行顺序不对后面会用到一个前面还没有创建的变量导致NameError。所以实际操作中要养成一个习惯检查代码之前先看每个单元格旁边的执行编号。如果某个输出异常先确认依赖单元格是否都已经运行过。最好的办法不是一个个手动点击而是用 Kernel → Restart Run All把所有单元格按顺序全部重新执行一遍确保当前状态是干净且一致的。3.4 内核重启和中断运行到死循环或非常耗时的计算时界面会一直显示[*]表示内核正在执行。这时候有两个选择。如果只是运行时间过长可以先等一下同时观察底部栏是否显示内核状态。如果确认永远跑不完或者代码本身有逻辑错误就点击 Kernel 菜单里的 Interrupt中断当前任务。Interrupt 相当于按下了CtrlC可以中断正在执行的 Python 代码但不会关闭内核。如果内核本身卡死或者你清空了所有变量想重新开始可以选择 Kernel → Restart Kernel。重启后之前定义的所有变量、函数都会被清掉所有单元格左侧的In [数字]编号也会清零。需要从第一个单元格重新执行一遍。注意内核重启不会自动运行任何单元格。执行结果不会保留在内核里只能从文档输出区域看到历史输出。如果需要恢复完整计算状态必须手动运行相关单元格或执行 Restart Run All。4. Jupyter Notebook、JupyterLab、PyCharm到底选哪个4.1 JupyterLab 和 Notebook 的真实差异JupyterLab 是 Jupyter 生态的新一代界面可以把它理解为 Jupyter Notebook 的升级版本。两者不是互斥关系Anaconda 安装后通常两个都能用。从使用体验上看JupyterLab 更像一个集成工作台。它可以在同一个页面打开多个 Notebook可以拖拽文件可以打开终端可以查看 CSV 文件内容还可以分区域排列不同文档。经典 Jupyter Notebook 则是单文档界面打开多个 Notebook 需要多个浏览器标签页。如果你主要用单个.ipynb文件做数据分析二者差别没有想象中大。代码执行逻辑、内核机制、单元格操作完全一样。差别主要集中在多任务管理体验上。一个比较常见的现象是jupyter notebook命令在新版本中可能默认打开的是 JupyterLab 界面而不是经典 Notebook 界面。这是因为安装的包可能包含jupyterlab而命令指向的入口发生了变化。经典 Notebook 界面要么通过 Anaconda Navigator 单独启动要么在 JupyterLab 中把界面切换成传统模式。4.2 在 PyCharm 里使用 Jupyter Notebook 的两种方式PyCharm 是很多 Python 开发者的主力 IDE它也能在一定程度上使用 Jupyter Notebook。PyCharm 专业版内置了 Jupyter 支持。你可以直接新建一个.ipynb文件PyCharm 会自动要求配置一个 Jupyter 服务器通常默认使用本地服务器。它本质上是把 PyCharm 变成一个 Notebook 前端代码仍然由后端的 Jupyter 内核执行。这样既能享受 PyCharm 的代码补全、重构能力也能保留交互式运行方式。PyCharm 社区版不内置 Jupyter 支持。一种替代方式是在 PyCharm 的终端里执行jupyter notebook它会弹出本地服务页面你可以在浏览器中使用 Notebook。虽然这不是真正的 IDE 集成但日常写代码、观察输出已经足够。如果你更习惯 PyCharm 的调试功能也有另一种思路把核心逻辑写成.py模块在 Notebook 中import这些模块用 Notebook 做数据分析和参数探索。这样兼顾了两种工具的强项。4.3 怎么根据任务类型选工具我的判断标准比较简单如果任务是纯数据探索、画图、模型调参优先用 JupyterLab 或 Jupyter Notebook。如果项目已经进入工程化阶段涉及模块拆分、单元测试、多人协作主体代码应该放在 PyCharm 或 VS Code 中写.py文件。如果是教学、演示、做教程Jupyter Notebook 仍然是最合适的因为它可以同时展示文字解释和代码流程。如果你一直在 PyCharm 里开发不想切换到浏览器可以试试专业版的 Notebook 集成。但它不是所有情况都比原生 Notebook 流畅遇到界面卡顿或兼容问题时优先看内核配置。下面的表可以帮你快速判断。使用场景推荐工具理由学习 Python 基础Jupyter Notebook上手简单按单元格运行数据分析 / 可视化JupyterLab多标签页支持 PDF、CSV 预览工程开发PyCharm / VS Code调试、测试、重构能力强教学演示Jupyter Notebook图文和代码混排效果好5. 常见问题排查空白页面、浏览器打不开、启动失败5.1 Windows 上打开后空白页先按这个顺序排查Windows 上使用 Jupyter Notebook最常遇到的问题是启动命令执行成功终端里显示服务已运行但浏览器打开http://localhost:8888时页面一片空白。很多人第一反应是重新安装其实大多数情况下不需要。建议按照下面的顺序排查。先看启动 Jupyter 的那个终端窗口。如果终端里持续刷错误日志比如“Permission denied”“Address already in use”“ModuleNotFoundError”问题根本不在浏览器而是服务没有正常启动或被提前终止。再看端口。如果 8888 端口被其他程序占用Jupyter 会提示端口占用这时可以换一个端口启动jupyter notebook --port 8889如果这个问题经常出现也可以在配置文件中指定固定端口。排除端口之后再处理浏览器问题。浏览器缓存、插件、代理设置都可能干扰本地页面的加载。可以先禁用浏览器扩展或者使用无痕模式打开试试。还是不行就换一个浏览器访问。还有一个容易忽略的问题杀毒软件或防火墙拦截了本地端口。Jupyter 服务默认监听本地地址正常情况不需要公网访问但某些安全软件会拦截进程间的本地通信。如果前面都查过没有解决问题可以看一下安全软件是否拦截了 python 进程。5.2 如何在其他浏览器打开启动 Jupyter Notebook 后终端通常会输出一行地址格式类似http://127.0.0.1:8888/tree?token一串字符由于 Jupyter 默认会调用系统默认浏览器打开如果你想用其他浏览器访问最简单的办法是复制这行地址粘贴到目标浏览器的地址栏里打开。只要服务还在运行浏览器通过同一地址就能访问同一个服务。如果你希望每次启动时都自动打开指定浏览器需要修改 Jupyter 配置文件。在命令行执行jupyter notebook --generate-config这会生成一个jupyter_notebook_config.py配置文件。在文件中找到或添加下面这行c.NotebookApp.browser C:/Program Files/Google/Chrome/Application/chrome.exe %s把路径改成你要使用的浏览器实际路径然后重启 Jupyter。这里有点容易出错因为路径必须和浏览器安装位置完全一致且%s不能省略它是 Jupyter 用来传递待打开地址的占位符。5.3 终端日志是排查的第一现场无论什么问题最需要先看的一定是启动 Jupyter 的终端日志。Jupyter 启动时会在终端里输出大量信息包括当前使用的配置路径、服务端口、内核路径、可能出现的异常堆栈。有一条经验很重要不要只盯着浏览器页面看报错浏览器页面经常会把真实错误掩盖掉。页面上显示 404、500、连接断开终端里往往有更具体的异常原因。另外打开一个 Notebook 之后如果代码运行报错报错内容会直接显示在单元格输出区域。这类错误大多是代码问题和 Jupyter 工具本身无关。常见的有ModuleNotFoundError、FileNotFoundError、SyntaxError。处理思路通常是先确认当前 Notebook 用的内核是哪个环境再确认那个环境里是否安装了对应依赖。如果内核启动失败页面会提示“Kernel died”或类似信息。这类问题经常是环境冲突导致的比如笔记本内核指向的 Python 版本和某个包不兼容。可以先尝试在终端里执行jupyter kernelspec list查看当前可用内核以及内核对应的路径。如果发现内核路径不对可以删除或重新配置也可以直接新建一个虚拟环境后重新安装 ipykernel。现象优先排查点处理方向页面空白终端日志、端口占用、浏览器插件换端口、换浏览器、清理缓存连接断开启动终端是否被关闭重新启动 Jupyter代码运行报错当前内核环境检查依赖环境、重新安装包内核死亡内核环境冲突删除或重配内核默认打开错误浏览器配置文件修改 NotebookApp.browser6. 把 Notebook 用得更顺手的几个重要细节6.1 常用快捷键和操作习惯熟练掌握快捷键效率提升非常明显。以下是新人比较需要的一组。快捷键作用ShiftEnter运行当前单元格并移动到下一个CtrlEnter运行当前单元格但不移动A在当前单元格上方插入一个单元格B在当前单元格下方插入一个单元格M切换为 Markdown 单元格Y切换为 Code 单元格D D连续按两次 D删除当前单元格C/X/V复制 / 剪切 / 粘贴单元格CtrlS保存Tab代码补全macOS 上Ctrl键通常对应的是Cmd键这一点在不同系统下会有些差异。除了快捷键也要培养好习惯在代码单元格里加注释用 Markdown 单元格记录每一步的想法。很多人刚开始只写代码回头再看 Notebook 时完全想不起来当时为什么这么处理。Notebook 最重要的优势之一就是“代码 解释 结果”能放在一起不利用这个优势就有点浪费。6.2 几个实用的魔法命令Jupyter Notebook 内置了一些魔法命令以%开头不是 Python 本身的语法但能极大方便交互式使用。%matplotlib inline是最常见的一个。在 Notebook 顶部运行它之后Matplotlib 绘制的图表会直接显示在单元格下方而不是弹出一个单独窗口。对数据分析非常实用建议每个涉及画图的 Notebook 都加上。%timeit可以测试一行代码的平均运行时间%timeit sum(range(1000))%%time放在单元格开头可以统计整个单元格的运行耗时。这个命令比较适合观察一整段训练代码的执行时间。如果要临时查看当前内核环境中的变量可以用%who它会列出当前已经定义的所有变量名。这样可以快速确认前面运行了哪些单元格、变量是否存在。如果需要在 Notebook 中执行系统命令可以在命令前加!比如!dir在 Windows 上运行的是目录列表在 macOS / Linux 上等价于ls。这个技巧经常用来快速查看当前目录的文件不用切回终端。6.3 真实项目里的边界文件大小、版本控制、顺序依赖当 Notebook 从练习走向真实项目时有几个问题要提前意识到。第一是.ipynb文件不适合版本控制。它的本质是 JSON 文档每个单元格的输出、图片、执行号都会保存下来。如果代码运行了几次输出内容不同git 对比时会看到大量无意义的差异。团队协作时尽量在提交前清空输出或者把重要代码抽成.py模块再纳入版本控制。第二是输出内容过多会导致文件体积快速膨胀。一个单元格打印几万行日志图片输出分辨率很高保存后文件可能从几十 KB 膨胀到几十 MB。浏览器打开这种 Notebook 会明显变慢。建议在正式保存前清掉不必要的大输出保留结论性结果即可。第三是顺序依赖问题。因为 Notebook 不强制从上到下执行别人拿到你的文件后如果直接运行其中某个单元格很可能因为前面某些变量还没定义而报错。为了让文件可复现建议分享前用 Restart Run All 完整执行一遍。执行通过后再检查每个单元格的输出是否正常。第四是安全边界。Notebook 可以执行任意 Python 代码也包括读文件、删除文件等操作。下载别人分享的.ipynb文件后不要盲目运行所有单元格。先看一遍代码内容确认安全后再执行。这个建议不仅适用于 Notebook也适用于所有来源不明的代码文件。最后说句实在话学习 Jupyter Notebook 最好的方式不是看长篇教程而是打开界面新建一个 Notebook让自己的手先动起来。先跑通一个简单打印再画一张图再把文字和代码混排起来。等用过一段时间再回头理解内核、环境变量、配置文件这些概念会轻松很多。不要一开始就在工具选型上纠结Notebook 也好JupyterLab 也好PyCharm 也罢都是执行代码的载体。真正值钱的是你把代码、数据、判断和结果记录下来并讲清楚的能力。而这个能力Jupyter Notebook 恰好是最适合用来练手的地方。