Jupyter Notebook 快速入门：从安装到魔法命令的完整指南

之前在学习吴恩达老师的深度学习课程时初次接触编程练习就遇到了.ipynb文件。很多同学会先愣一下代码不是写在.py文件里吗为什么课程里给出的是一堆网页文件当时我也是一样的困惑。后来花了一点时间把 Jupyter/iPython Notebook 的核心用法和常见的坑点理了一遍才发现它其实非常适合做数据分析、课程作业和快速实验。本文围绕 Jupyter/iPython Notebook 快速入门整理了一套完整的使用指南包含环境安装、界面操作、Magic 命令、完整示例、常见报错排查以及工程化建议。文章关键词汇会保留中英文对照方便在吴恩达课程C1W2L17中对照理解。无论你是第一次接触 Notebook 的零基础新手还是平时只写.py脚本、想快速上手交互式开发的开发者这篇教程都值得收藏。1. 背景与核心概念1.1 什么是 Jupyter NotebookJupyter Notebook 是一个基于 Web 浏览器的交互式开发环境。它的核心交互单元叫作“单元格Cell”每个单元格可以写入代码、Markdown 文本或纯文本。用户可以一次运行一个单元格也可以在同一个 Notebook 文档中组织代码、输出、图表和说明文字。理解 Jupyter Notebook需要先理解 IPython。IPython 是一个增强版的 Python 交互式 Shell它提供了更友好的提示符、Tab 补全、历史记录和魔法命令。Jupyter 项目最初就是基于 IPython 发展起来的所以它的旧称是 IPython Notebook。后来项目扩展为支持多种编程语言的内核才改名为 Jupyter并支持 Python、R、Julia 等语言。在吴恩达深度学习课程中编程作业通常直接提供一个.ipynb文件。你只需要按照题目要求在对应的单元格中补全代码然后执行并查看输出。这种方式比传统的“编写完整 Python 脚本 手动运行”更适合教学场景因为它能把问题拆解成多个小步骤每一步的输出也能立刻反馈。1.2 Jupyter Notebook 与 JupyterLab 的区别很多人会混淆jupyter notebook和jupyter lab这两条命令。简单来说JupyterLab 是 Jupyter Notebook 的“升级版”集成开发环境。它保留了单元格执行的核心体验同时提供了文件管理、终端、文本编辑、多标签页拖拽布局等更强的功能。对比项Jupyter NotebookJupyterLab启动命令jupyter notebookjupyter lab界面风格单一文档编辑页多标签页 IDE 风格文件管理支持但比较基础更强支持拖拽分屏扩展能力较少丰富的扩展系统适合场景快速看结果、课程作业日常开发、多文件协作如果你是跟着吴恩达课程学习直接用jupyter notebook就可以了因为课程提供的.ipynb文件在两种环境下都能打开。如果你平时还需要写脚本、看终端、管理数据集可以尝试 JupyterLab。两者的核心概念相同学会一个另一个基本能无缝切换。1.3 Notebook 的工作原理Notebook 的本质是一个“浏览器前端 后端内核Kernel”的架构。浏览器负责显示界面和交互真正执行代码的是后台的 Python 进程。当你点击运行单元格时浏览器会把代码发送给内核内核执行完成后再把结果返回给浏览器显示。内核是有状态的。也就是说你在第一个单元格里定义的变量在后续单元格中是“记得”的。这是 Notebook 与普通脚本最大的区别之一也是新手最容易踩坑的地方如果你没有按顺序运行整个文件某个变量可能还没定义或者被旧值覆盖。所以遇到结果不对时第一反应通常不是改代码而是先 Kernel 菜单里“Restart Run All”把所有单元格按顺序重新执行一遍。2. 环境准备与版本说明2.1 安装方式想要运行 Jupyter Notebook最简单的方式是安装 Anaconda。Anaconda 自带 Python、Jupyter Notebook 和大量常用数据分析库安装之后就不需要单独处理 Jupyter 的依赖关系尤其适合刚入门 Python 的课程学习者。如果你已经安装了 Python也可以只通过 pip 安装 Jupyterpip install jupyter安装完成后在命令行输入以下命令验证是否成功jupyter --version如果能输出版本号列表说明 Jupyter 已经安装完成。本文不会绑定某个具体版本的 Jupyter因为 Notebook 的升级迭代比较快只要你的环境是基于 Python 3.x 的常见版本操作步骤基本都是通用的。2.2 启动 Notebook启动 Jupyter Notebook 非常直接在终端中进入你想要工作的目录然后运行jupyter notebook正常情况下终端会输出类似下面的日志[I NotebookApp] Serving notebooks from local directory: /Users/xxx/ai_learning [I NotebookApp] Jupyter Notebook is running at: [I NotebookApp] http://localhost:8888/?token...Jupyter 会启动一个本地服务默认端口是 8888并在默认浏览器中自动打开页面。如果浏览器没有自动打开可以手动复制终端里的http://localhost:8888/?token...地址粘贴到浏览器中访问。如果想指定端口或目录可以使用jupyter notebook --port 8899 --notebook-dirD:/ai_learning这里--notebook-dir指定的是待办工作区的根目录Jupyter 文件列表中只会显示这个目录下的文件。如果你希望 Notebook 能访问其他目录下的文件可以把所有相关文件统一放在同一个工作目录中或者使用绝对路径引用。2.3 课程环境建议学习吴恩达深度学习课程时建议专门创建一个独立的 Python 环境避免和其他项目互相污染。使用 Anaconda 的话可以这样创建conda create -n deeplearning python3.9 conda activate deeplearning接下来在这个环境中安装 Jupyter 和课程可能用到的 NumPy、Matplotlib 等库pip install jupyter numpy matplotlib这样做的好处是即使以后在其他项目里安装了不同版本的包也不会影响课程作业的运行。如果后续遇到依赖冲突直接重建一个环境即可成本很低。3. 核心操作与界面拆解3.1 Notebook 界面组成打开一个.ipynb文件后你会看到以下几个核心区域菜单栏Menu Bar包含 File、Edit、View、Insert、Cell、Kernel、Help 等菜单。工具栏Toolbar提供保存、插入单元格、剪切、运行、停止等快捷按钮。单元格列表每个 Notebook 由多个单元格按顺序组成。内核状态指示右上角的圆形图标空心表示内核空闲实心表示内核正在运行。单元格主要分为三种类型Code代码、Markdown富文本说明、Raw原样输出。默认新建的单元格是 Code 类型。Markdown 单元格不会执行代码而是会被渲染为带格式的文本非常适合写题目说明、公式和笔记。3.2 单元格与快捷键在 Notebook 中快捷键能显著提高编写效率。这里需要先理解两种模式命令模式按Esc进入此时按键作用于整个单元格比如删除、复制、切换类型。编辑模式按Enter进入此时光标在单元格内部可以正常输入代码。常用快捷键如下操作快捷键运行当前单元格Ctrl Enter运行并跳到下一格Shift Enter在上方插入单元格命令模式下按A在下方插入单元格命令模式下按B删除单元格命令模式下按两次D切换为 Markdown命令模式下按M切换为 Code命令模式下按Y撤销删除命令模式下按Z这些快捷键不需要一次全部记住先掌握Shift Enter、A、B、M、Y基本就可以顺畅地完成课程作业了。3.3 Markdown 单元格Markdown 单元格是在 Notebook 中写说明文字的主要方式。下面是一个最简示例# 这是一个一级标题 ## 这是一个二级标题 - 这是列表项 - 这是另一个列表项 **加粗文字** 和 *斜体文字* 这是一个公式$\hat{y} \sigma(z)$运行这个 Markdown 单元格之后它会渲染为漂亮的富文本。在吴恩达课程中每个练习前面通常都有大段 Markdown 说明包含问题描述、数学公式和示例输出。阅读这些说明时不需要编辑它们如果误触导致内容被修改可以用Ctrl Z撤销或者从课程页面重新下载原始文件。3.4 魔法命令Magic Commands魔法命令是 IPython 提供的一类特殊指令以%开头。它们不是 Python 语法但能极大简化 Notebook 使用体验。下面几个是最常用的# 让 Matplotlib 图片直接嵌入 Notebook %matplotlib inline # 测试一行代码的运行时间 %timeit sum(range(1000000)) # 在单元格中运行 Shell 命令Windows 下使用 !dir !ls # 将单元格内容写入文件 %%writefile demo.py print(hello from demo.py)其中%matplotlib inline在做数据可视化时几乎必用。没有这行命令绘图窗口可能会弹出到外部或者无法显示加上之后图片会直接显示在单元格下方。%%writefile则可以用来在 Notebook 中直接生成一个.py文件。如果你希望养成“课程作业完成后导出一份纯脚本”的习惯这个命令很实用。3.5 如何创建.py文件Notebook 的默认保存格式是.ipynb它本质上是一个 JSON 文件。但有几种方式可以让你在 Notebook 工作流中创建或导出.py文件。第一种方式使用魔法命令%%writefile my_script.py import numpy as np arr np.array([1, 2, 3]) print(arr.mean())执行后Notebook 同目录下会生成my_script.py。第二种方式使用菜单导出打开 File 菜单。选择 Download as。选择 Python (.py)。这个操作可以把整个 Notebook 的代码单元格合并成一个.py文件Markdown 内容会被转换为注释适合提交给无法直接打开.ipynb的环境。第三种方式使用命令行导出jupyter nbconvert --to script first_notebook.ipynb执行后会在当前目录生成first_notebook.py。这种方式可以批量转换文件适合最后整理项目代码。3.6 内核管理Notebook 右上角的内核状态对排查问题非常关键。当单元格长时间运行没有输出时可以点击工具栏上的“Stop”按钮强制中止当前任务当变量状态混乱、运行结果不符合预期时建议通过菜单“Kernel - Restart Clear Output”清空所有输出并重启内核然后再重新运行。在“Kernel - Change Kernel”中你可以切换不同的 Python 环境。如果你在 Anaconda 中创建了多个环境可能需要先在命令行安装ipykernel并注册内核conda activate deeplearning pip install ipykernel python -m ipykernel install --user --name deeplearning --display-name Python (deeplearning)这样在 Notebook 的内核列表里就能看到名为Python (deeplearning)的选项了。3.7 用 Notebook 做演示与幻灯片Notebook 也可以用来做幻灯片。不过常见的困惑是点击“Notebook 的 PPT 制作按钮没有反应”。这通常是因为默认情况下浏览器打开的是普通 Notebook 页面并没有进入演示模式。如果你想制作幻灯片一般推荐两种方案使用nbconvert导出 HTML 幻灯片jupyter nbconvert --to slides your_notebook.ipynb安装 RISE 扩展这样可以在 Notebook 中直接进入幻灯片演示模式pip install RISE jupyter nbextension install rise --py --sys-prefix jupyter nbextension enable rise --py --sys-prefix需要注意RISE 的安装和 Jupyter 版本有关如果安装失败可以优先考虑nbconvert导出方案。4. 完整实战案例用 Notebook 完成一个小型示例下面通过一个完整的案例把前面提到的概念串起来。我们会创建一个 Notebok在其中写入标题、说明文字、Python 代码、可视化图表并导出.py脚本。你可以照着一遍跑通之后再迁移到课程作业中。4.1 创建项目结构先在工作目录下新建一个文件夹mkdir jupyter_quickstart cd jupyter_quickstart启动 Jupyterjupyter notebook在页面右上角点击“New - Python 3”即可创建一个新的 Notebook。我们可以把它重命名为first_notebook.ipynb。4.2 编写核心单元格第一个单元格使用 Markdown负责写标题和说明# 第一个 Notebook 示例 这个 Notebook 用于演示 Jupyter/iPython Notebook 的基础用法。 - 写代码 - 写说明文字 - 生成并导出 .py 文件第二个单元格是代码先导入数据分析库并设置图片内嵌显示import numpy as np import matplotlib.pyplot as plt %matplotlib inline print(Notebook is running successfully!)预期输出Notebook is running successfully!第三个单元格演示变量状态共享x np.linspace(0, 10, 100) y np.sin(x) print(x length:, len(x)) print(y first item:, y[0])第四个单元格绘制一张简单折线图plt.plot(x, y) plt.title(Sin Curve) plt.xlabel(x) plt.ylabel(sin(x)) plt.grid(True) plt.show()第五个单元格用%%writefile生成一个.py文件%%writefile generated_script.py import numpy as np import matplotlib.pyplot as plt x np.linspace(0, 10, 100) y np.sin(x) plt.plot(x, y) plt.title(Generated from Notebook) plt.show()4.3 运行与验证依次运行以上单元格。注意第二个单元格运行后变量x和y会保留在内存中第四个单元格运行后Notebook 中会直接显示一条正弦曲线图第五个单元格运行后当前目录会出现一个generated_script.py文件。如果中间某个单元格报错使用菜单“Kernel - Restart Run All”让 Notebook 按从头到尾的顺序重新执行。只要环境没有问题最终整个 Notebook 应该可以顺利跑完。4.4 导出脚本与分享当我们想把这个 Notebook 转成纯 Python 脚本时可以执行jupyter nbconvert --to script first_notebook.ipynb转换后的first_notebook.py会保留所有代码单元格中的代码并把 Markdown 单元格变成#注释。这个文件非常适合放入 Git 仓库做代码审查也方便在普通 Python 环境中运行。5. 常见问题与排查思路5.1 “jupyter” 不是内部或外部命令也不是可运行的程序这是在 Windows 命令行中很常见的报错。根本原因是系统没有找到jupyter可执行文件的路径通常有几种情况Jupyter 没有安装成功。安装的是 Anaconda但安装时没有勾选“Add to PATH”。当前命令行没有激活 Anaconda 对应环境。排查时先确认 Jupyter 是否真的装上了。在终端执行python -m jupyter --version如果这条命令能输出版本信息说明 Jupyter 已安装只是 PATH 没有配置好。更稳妥的方式是直接使用 Python 模块启动python -m jupyter notebook这种方法不需要依赖jupyter命令是否在 PATH 中。如果你希望命令行直接使用jupyter可以在 Anaconda Prompt 中启动或者重新安装 Anaconda 时勾选 PATH 选项然后重启终端。5.2 Windows 上打开 Jupyter Notebook 后空白很多用户在 Windows 上运行jupyter notebook后浏览器打开页面却一片空白没有任何内容。这个问题的原因比较多需要按顺序排查。先确认终端日志里是否出现http://localhost:8888/?token...地址。如果出现了可能是默认浏览器和 Jupyter 前端资源加载不兼容可以尝试复制该地址手动粘贴到 Chrome 或 Firefox 中访问。接下来尝试清理浏览器缓存或者更换端口jupyter notebook --port 8899如果依然空白可以重启 Jupyter 配置jupyter notebook --generate-config最后考虑重装或升级相关包pip install --upgrade jupyter notebook多数情况下换成 Chrome 浏览器并重新复制带 token 的完整地址能解决大部分空白问题。5.3 启动后目录不对或如何在其他浏览器打开Jupyter 展示的文件列表始终以启动目录为根目录。如果你希望在某个特定目录下工作有两种常见做法。第一种先进入目标目录再启动 Jupytercd D:/ai_learning/course1 jupyter notebook第二种启动时指定目录jupyter notebook --notebook-dirD:/ai_learning/course1如果你的项目最终要在 JupyterLab 中切换目录可以在左侧文件浏览器中点击文件夹进入也可以通过顶部菜单“File - Open from Path”直接输入完整路径。不过要注意JupyterLab 能访问的目录范围依然受启动目录限制。关于“如何在其他浏览器打开”的问题最直接的方式是复制终端输出的完整地址粘贴到你想用的浏览器中。如果希望 Jupyter 自动使用某个浏览器可以在配置文件中设置NotebookApp.browser但不同系统下浏览器启动命令不太一样建议直接手动复制地址简单且可靠。5.4 在 PyCharm 中使用 Jupyter NotebookPyCharm 的一些版本对 Jupyter Notebook 支持得比较好。如果你使用的是 PyCharm Professional可以直接打开.ipynb文件并在设置中配置 Jupyter Server。它允许你在 PyCharm 内部编辑和运行单元格体验和浏览器端基本相同。如果你使用的是 PyCharm Community 版内置支持会弱一些。常见做法是在终端启动jupyter notebook然后在 PyCharm 的浏览器中打开对应地址把浏览器端当独立工具使用。另外PyCharm 本质是 Python IDE它可以直接运行.py文件。如果你不太习惯 Notebook 这种交互方式可以使用jupyter nbconvert --to script把.ipynb转为.py再在 PyCharm 中运行。不过课程作业通常希望保留.ipynb中 Markdown 说明和代码单元格结构所以还是推荐至少掌握浏览器端的 Notebook 操作。5.5 云平台或在线 Notebook 无法访问不少在线数据科学平台和竞赛平台都提供云端 Notebook用户不需要在本地安装任何东西。访问流程通常是在平台控制台创建 Notebook 实例然后点击“打开”按钮浏览器会跳转到内嵌的 Notebook 页面。这种页面本质上还是 Jupyter Notebook只是运行环境在云端。如果页面无法访问一般要先检查实例是否已启动、网络是否通畅、浏览器是否存在缓存问题。不同平台的具体限制可能不同但核心排查思路和本地 Notebook 类似先看页面控制台状态再尝试更换浏览器或清理缓存。5.6 点击 PPT 制作没有反应有些版本的 Notebook 工具栏会有“幻灯片”相关功能。如果点击后没有反应通常是因为环境中缺少幻灯片导出依赖或者当前.ipynb没有切换到幻灯片模式。纯 Jupyter 环境下推荐使用命令行导出jupyter nbconvert --to slides presentation.ipynb或者使用 RISE 扩展进入演示模式。RISE 的安装方式在前面已经介绍过。如果你只是一次性做一个课程汇报建议直接选择“File - Download as - HTML”然后用浏览器全屏展示可能更省事。6. 最佳实践与工程建议6.1 用虚拟环境隔离依赖Notebook 和普通 Python 脚本一样也受到当前 Python 环境的影响。很多“代码在别人电脑上能跑在我这里报错”的问题本质上都是依赖版本不一致。因此强烈建议为每个课程或项目单独创建虚拟环境。使用 Anaconda 时可以这样做conda create -n deeplearning python3.9 conda activate deeplearning pip install jupyter ipykernel python -m ipykernel install --user --name deeplearning --display-name Python (deeplearning)之后每次打开 Notebook通过 Kernel - Change Kernel 选择对应环境即可。环境需要迁移时可以导出配置文件conda env export environment.yml这样即使换一台电脑也能快速还原环境。6.2 保持良好的 Notebook 排版习惯写 Notebook 不只是写代码更是写一份可读的文档。建议每个阶段先写一个 Markdown 标题概括下面代码要完成的任务关键变量使用有意义的命名输出过长时避免打印大量噪声数据。课程作业中尤其要注意不要删除题目自带的 Markdown 单元格也不要把无关的大型变量直接输出到页面上。保持整洁不仅方便自己检查也方便老师或同事 review。如果多个单元格都要用到同一条数据处理逻辑可以考虑尽早把公共函数收进.py文件再在 Notebook 中import。这样既能利用 Notebook 的交互性又让代码保持模块化。6.3 正确处理.ipynb的版本控制.ipynb文件是 JSON 格式Git 会把它当成普通文本处理。只要输出结果变化整个文件就可能产生大量 diff导致合并冲突非常频繁。一个比较实用的做法是在 Git 仓库中同时维护.ipynb和导出的.py文件。Notebook 负责交互演示脚本负责代码审查。对于输出内容可以用nbstripout工具清除单元格输出后再提交pip install nbstripout nbstripout --installnbstripout会注册一个 Git filter后续每次提交时自动清理输出。这样版本库不会因为输出内容而频繁变动但本地打开依然能看到原来的输出。6.4 注意工作目录与路径问题Notebook 的“当前工作目录”不一定等于.ipynb文件所在目录这一点容易被忽略。如果你在 Notebook 中读取相对路径文件可能会报“文件不存在”。建议在 Notebook 开头显式打印当前工作目录并切换到脚本所在目录import os print(os.getcwd()) os.chdir(os.path.dirname(os.path.abspath(__file__)))需要注意的是直接使用__file__在 Notebook 中并不总是有效更稳妥的方式是使用os.path.abspath(.)查看实际路径或者直接使用绝对路径。路径中尽量避免中文和空格能减少很多跨平台问题。6.5 安全边界与敏感信息不要将 API Key、数据库密码等敏感信息直接写在 Notebook 单元格里。.ipynb会保存所有输入输出一旦分享或提交到 Git敏感信息就会泄露。推荐的做法是使用环境变量或本地配置文件import os my_token os.getenv(MY_API_TOKEN) print(Token loaded:, bool(my_token))在命令行中设置环境变量或者使用.env文件同时确保.env被加入.gitignore。这也是生产环境开发中非常重要的习惯。7. 总结与学习路线这篇文章从 Jupyter/iPython Notebook 的背景讲起介绍了 Notebook 与 IPython 的关系、Jupyter Notebook 与 JupyterLab 的区别以及它背后的“浏览器前端 内核”工作原理。围绕课程场景重点整理了环境安装、启动方式、单元格类型、快捷键、Markdown 写法、魔法命令和.py文件导出方法并通过一个完整示例带你把整个流程跑通。日常使用中高频问题主要集中在“jupyter 不是内部或外部命令”“启动后空白”“目录不对”“PyCharm 怎么用”这几个方向上。排错时先确认环境变量和安装状态再尝试浏览器和端口切换最后考虑重启内核或重装依赖大部分问题都能解决。下一步如果你要继续深入学习可以关注这几个方向JupyterLab 的文件管理与扩展生态、Widgets 交互式控件、RISE 幻灯片演示、Voila 将 Notebook 变成 Web 应用以及不同语言的 Jupyter 内核例如 xeus 系列内核支持多种语言。不过对于吴恩达课程来说当前掌握的能力已经足够完成绝大多数编程练习了。最后想提醒的是Notebook 只是工具核心还是你对问题的拆解和对代码的理解。建议把本文提到的快捷键和魔法命令各试一遍然后回到课程第一课打开一个.ipynb文件按自己的节奏完成一次单元格执行。遇到问题也不用慌重启内核、清空输出、重新运行通常能解决一大半。如果本文对你有帮助可以收藏备用有疑问也欢迎在评论区一起交流。