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

之前在学习吴恩达老师的深度学习课程时，初次接触编程练习就遇到了.ipynb文件。很多同学会先愣一下：代码不是写在.py文件里吗？为什么课程里给出的是一堆网页文件？当时我也是一样的困惑。后来花了一点时间把 Jupyter/iPython Notebook 的核心用法和常见的坑点理了一遍，才发现它其实非常适合做数据分析、课程作业和快速实验。

本文围绕 Jupyter/iPython Notebook 快速入门整理了一套完整的使用指南，包含环境安装、界面操作、Magic 命令、完整示例、常见报错排查以及工程化建议。文章关键词汇会保留中英文对照，方便在吴恩达课程（C1W2L17）中对照理解。无论你是第一次接触 Notebook 的零基础新手，还是平时只写.py脚本、想快速上手交互式开发的开发者，这篇教程都值得收藏。

1. 背景与核心概念

1.1 什么是 Jupyter Notebook

Jupyter 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 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 安装 Jupyter：

pip 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-dir=D:/ai_learning

这里--notebook-dir指定的是待办工作区的根目录，Jupyter 文件列表中只会显示这个目录下的文件。如果你希望 Notebook 能访问其他目录下的文件，可以把所有相关文件统一放在同一个工作目录中，或者使用绝对路径引用。

2.3 课程环境建议

学习吴恩达深度学习课程时，建议专门创建一个独立的 Python 环境，避免和其他项目互相污染。使用 Anaconda 的话，可以这样创建：

conda create -n deeplearning python=3.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进入，此时光标在单元格内部，可以正常输入代码。

常用快捷键如下：

这些快捷键不需要一次全部记住，先掌握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

启动 Jupyter：

jupyter 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 展示的文件列表始终以启动目录为根目录。如果你希望在某个特定目录下工作，有两种常见做法。

第一种，先进入目标目录，再启动 Jupyter：

cd D:/ai_learning/course1 jupyter notebook

第二种，启动时指定目录：

jupyter notebook --notebook-dir=D:/ai_learning/course1

如果你的项目最终要在 JupyterLab 中切换目录，可以在左侧文件浏览器中点击文件夹进入，也可以通过顶部菜单“File -> Open from Path”直接输入完整路径。不过要注意，JupyterLab 能访问的目录范围依然受启动目录限制。

关于“如何在其他浏览器打开”的问题，最直接的方式是复制终端输出的完整地址，粘贴到你想用的浏览器中。如果希望 Jupyter 自动使用某个浏览器，可以在配置文件中设置NotebookApp.browser，但不同系统下浏览器启动命令不太一样，建议直接手动复制地址，简单且可靠。

5.4 在 PyCharm 中使用 Jupyter Notebook

PyCharm 的一些版本对 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 python=3.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 --install

nbstripout会注册一个 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文件，按自己的节奏完成一次单元格执行。遇到问题也不用慌，重启内核、清空输出、重新运行，通常能解决一大半。如果本文对你有帮助，可以收藏备用；有疑问也欢迎在评论区一起交流。