Jupyter Notebook#

简介#

Jupyter Notebook 是 Project Jupyter 旗下的一个笔记本文档创作应用程序。基于强大的计算型笔记本文档格式，Jupyter Notebook 提供了快速、交互式的新方法来构建代码原型并进行解释、探索和可视化数据，以及与他人分享您的想法。

笔记本文档将基于控制台的交互式计算方法提升到了一个全新的方向，提供了一个基于 Web 的应用程序，适用于捕获整个计算过程：开发、记录和执行代码，以及传达结果。Jupyter Notebook 包含两个组件：

Web 应用程序： 一个基于浏览器的编辑程序，用于交互式创作计算型笔记本文档，为代码原型设计和解释、数据探索和可视化以及与他人分享想法提供了一个快速的交互式环境。

计算型笔记本文档： 一种可共享的文档，它将计算机代码、自然语言描述、数据、丰富的可视化内容（如 3D 模型、图表、数学公式、图形和插图）以及交互式控件结合在一起。

另请参阅

请参阅安装指南，了解如何安装 notebook 及其依赖项。

Web 应用程序的主要功能#

  • 在浏览器内编辑代码，具有自动语法高亮、缩进和 Tab 补全/内省功能。

  • 能够从浏览器执行代码，并将计算结果附加到生成它们的代码上。

  • 使用富媒体表示形式显示计算结果，例如 HTML、LaTeX、PNG、SVG 等。例如，由 [matplotlib] 库渲染的出版级质量的图形，可以内联包含。

  • 使用 [Markdown] 标记语言在浏览器内编辑富文本，这可以为代码提供注释，而不仅限于纯文本。

  • 能够使用 LaTeX 轻松地在 Markdown 单元格中包含数学符号，并由 MathJax 进行本地渲染。

笔记本文档#

笔记本文档包含交互式会话的输入和输出，以及伴随代码但非用于执行的附加文本。通过这种方式，笔记本文档文件可以作为会话的完整计算记录，将可执行代码与解释性文本、数学公式和结果对象的丰富表示形式交错在一起。这些文档内部是 JSON 文件，并以 .ipynb 扩展名保存。由于 JSON 是纯文本格式，它们可以进行版本控制并与同事共享。

笔记本文档可以通过 [nbconvert] 命令导出为一系列静态格式，包括 HTML（例如，用于博客文章）、reStructuredText、LaTeX、PDF 和幻灯片。

此外，任何可从公共 URL 访问的 .ipynb 笔记本文档都可以通过 Jupyter Notebook Viewer <nbviewer> 共享。此服务从该 URL 加载笔记本文档，并将其渲染为静态网页。这样，结果就可以与同事共享，或作为公开的博客文章，而无需其他用户自己安装 Jupyter Notebook。实际上，nbviewer 只是作为 Web 服务的 [nbconvert]，因此您可以使用 nbconvert 进行自己的静态转换，而无需依赖 nbviewer。

另请参阅

关于 notebook JSON 文件格式的详细信息

笔记本文档与隐私#

因为您在网页浏览器中使用 Jupyter，所以有些人对用它处理敏感数据感到担忧是可以理解的。但是，如果您遵循了标准的安装说明，Jupyter 实际上是在您自己的计算机上运行的。如果地址栏中的 URL 以 https://: 或 http://127.0.0.1: 开头，那么是您的计算机在充当服务器。Jupyter 不会将您的数据发送到任何其他地方——而且由于它是开源的，其他人可以检查我们对此是否诚实。

您也可以远程使用 Jupyter：例如，您的公司或大学可能会为您运行服务器。在这些情况下，如果您想处理敏感数据，请与您的 IT 或数据保护人员讨论。

我们的目标是确保您浏览器中的其他页面或同一台计算机上的其他用户无法访问您的 notebook 服务器。有关此内容的更多信息，请参阅安全文档。

启动 notebook 服务器#

您可以使用以下命令从命令行启动一个 notebook 服务器：

jupyter notebook

这将在您的控制台中打印一些关于 notebook 服务器的信息，并打开一个网页浏览器，指向 Web 应用程序的 URL（默认为 http://127.0.0.1:8888）。

Jupyter Notebook Web 应用程序的登录页面，即仪表板，显示了 notebook 目录中当前可用的笔记本文档（默认情况下，是启动 notebook 服务器的目录）。

您可以通过New Notebook按钮从仪表板创建新的笔记本文档，或者通过点击其名称来打开现有的文档。您还可以将.ipynb笔记本文档和标准的.py Python 源代码文件拖放到笔记本文档列表区域。

从命令行启动 notebook 服务器时，您也可以使用 jupyter notebook my_notebook.ipynb 直接打开一个特定的笔记本文档，绕过仪表板。如果未提供扩展名，则假定为 .ipynb 扩展名。

当您在一个已打开的笔记本文档中时，File | Open... 菜单选项将在新的浏览器标签页中打开仪表板，以便您从 notebook 目录中打开另一个笔记本文档或创建一个新的笔记本文档。

注意

如果您想在不同的目录中处理笔记本文档，可以同时启动多个 notebook 服务器。默认情况下，第一个 notebook 服务器在端口 8888 上启动，后续的 notebook 服务器会搜索该端口附近的端口。您也可以使用 --port 选项手动指定端口。

创建一个新的笔记本文档#

可以随时创建一个新的笔记本文档，无论是在仪表板中，还是在活动笔记本文档中使用 文件 ‣ 新建 菜单选项。新的笔记本文档将在同一目录中创建，并在新的浏览器标签页中打开。它也会在仪表板的笔记本文档列表中显示为一个新条目。

a screencast showing how to create new notebooks from the user interface

打开笔记本文档#

一个打开的笔记本文档有且仅有一个连接到内核的交互式会话，该会话将执行用户发送的代码并返回结果。如果关闭网页浏览器窗口，此内核仍保持活动状态，从仪表板重新打开相同的笔记本文档将使 Web 应用程序重新连接到同一内核。在仪表板中，具有活动内核的笔记本文档旁边有一个Shutdown按钮，而没有活动内核的笔记本文档则在该位置有一个Delete按钮。

其他客户端可以连接到同一个内核。当每个内核启动时，notebook 服务器会在终端打印一条类似这样的消息：

[JupyterNotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373

这个长字符串是内核的 ID，足以获取连接到内核所需的信息。如果笔记本文档使用 IPython 内核，您还可以通过运行 %connect_info 魔术命令 来查看此连接数据，它将打印相同的 ID 信息以及其他详细信息。

然后，例如，您可以通过传递 ID 的一部分，从命令行手动启动一个连接到同一个内核的 Qt 控制台：

$ jupyter qtconsole --existing 87f7d2c0

如果没有 ID，--existing 将连接到最近启动的内核。

使用 IPython 内核，您还可以在笔记本文档中运行 %qtconsole 魔术命令 来打开一个连接到同一内核的 Qt 控制台。

另请参阅

解耦的双进程模型

Notebook 用户界面#

当您创建一个新的笔记本文档时，您将看到笔记本文档名称、菜单栏、工具栏和一个空的代码单元格。

a screenshot showing a blank notebook

笔记本文档名称：显示在页面顶部 Jupyter 徽标旁边的名称，反映了 .ipynb 文件的名称。点击笔记本文档名称会弹出一个对话框，允许您重命名它。因此，在浏览器中将笔记本文档从“Untitled0”重命名为“My first notebook”，会将 Untitled0.ipynb 文件重命名为 My first notebook.ipynb。

菜单栏：菜单栏提供了可用于操作笔记本文档功能的不同选项。

工具栏：工具栏提供了一种快速执行笔记本文档中最常用操作的方式，只需点击一个图标即可。

代码单元格：默认的单元格类型；请继续阅读以了解单元格的解释。

笔记本文档的结构#

笔记本文档由一系列单元格组成。单元格是一个多行文本输入字段，其内容可以通过使用 Shift-Enter，或点击工具栏上的“播放”按钮，或菜单栏中的 单元格、运行 来执行。单元格的执行行为由单元格的类型决定。有三种类型的单元格：代码单元格、Markdown 单元格和原始单元格。每个单元格最初都是一个代码单元格，但其类型可以通过使用工具栏上的下拉菜单（最初为“代码”）或通过键盘快捷键来更改。

有关在笔记本文档中可以做的不同事情的更多信息，请参阅示例集合。

代码单元格#

一个代码单元格允许您编辑和编写新代码，具有完整的语法高亮和 Tab 补全功能。您使用的编程语言取决于内核，默认内核（IPython）运行 Python 代码。

当代码单元格被执行时，其中包含的代码会发送到与笔记本文档关联的内核。然后，从该计算返回的结果将作为单元格的输出显示在笔记本文档中。输出不仅限于文本，还可能有许多其他可能的输出形式，包括 matplotlib 图形和 HTML 表格（例如，在 pandas 数据分析包中使用）。这被称为 IPython 的富显示功能。

另请参阅

[富输出] 示例笔记本文档

Markdown 单元格#

您可以使用富文本，以文学编程的方式记录计算过程，将描述性文本与代码交替出现。在 IPython 中，这是通过使用 Markdown 语言标记文本来实现的。相应的单元格称为 Markdown 单元格。Markdown 语言提供了一种简单的方法来执行此文本标记，即指定文本的哪些部分应该被强调（斜体）、加粗、形成列表等。

如果您想为文档提供结构，可以使用 Markdown 标题。Markdown 标题由 1 到 6 个井号 # # 后跟一个空格和您的章节标题组成。Markdown 标题将被转换为笔记本文档中该章节的可点击链接。在导出为其他文档格式（如 PDF）时，它也用作提示。

当执行 Markdown 单元格时，Markdown 代码会转换为相应的格式化富文本。Markdown 允许使用任意 HTML 代码进行格式化。

在 Markdown 单元格中，您还可以使用标准的 LaTeX 符号，以一种直接的方式包含数学公式：$...$ 用于行内数学公式，$$...$$ 用于独立显示的数学公式。当执行 Markdown 单元格时，LaTeX 部分会在 HTML 输出中自动渲染为具有高质量排版的方程式。这是由 MathJax 实现的，它支持 LaTeX 功能的很大一个子集。

由 LaTeX 和 AMS-LaTeX（amsmath 包）定义的标准数学环境也有效，例如 \begin{equation}...\end{equation} 和 \begin{align}...\end{align}。可以使用标准方法定义新的 LaTeX 宏，例如 \newcommand，只需将它们放在 Markdown 单元格中数学定界符之间的任何位置即可。这些定义随后在 IPython 会话的其余部分都可用。

另请参阅

[使用 Markdown 单元格] 示例笔记本文档

原始单元格#

原始单元格提供了一个可以直接编写输出的地方。原始单元格不由笔记本文档评估。当通过 [nbconvert] 传递时，原始单元格会未经修改地到达目标格式。例如，您可以在原始单元格中输入完整的 LaTeX，它只会在通过 nbconvert 转换后由 LaTeX 渲染。

基本工作流程#

因此，在笔记本文档中的正常工作流程与标准的 IPython 会话非常相似，不同之处在于您可以多次就地编辑单元格，直到获得期望的结果，而不必使用 %run 魔术命令重新运行单独的脚本。

通常，您会分块处理一个计算问题，将相关的想法组织到单元格中，并在前面的部分正常工作后继续前进。这对于交互式探索来说，比将计算分解为必须一起执行的脚本要方便得多，尤其是在其中某些部分需要很长时间才能运行时，以前这是必需的。

要中断一个耗时过长的计算，请使用 内核、中断 菜单选项，或键盘快捷键 i,i。同样，要重新启动整个计算过程，请使用 内核、重启 菜单选项或 0,0 快捷键。

笔记本文档可以作为 .ipynb 文件下载，或使用菜单选项 文件、下载为 转换为多种其他格式。

另请参阅

[在 Jupyter Notebook 中运行代码] 示例笔记本文档

[Notebook 基础] 示例笔记本文档

键盘快捷键#

笔记本文档中的所有操作都可以用鼠标完成，但最常用的操作也有键盘快捷键。需要记住的基本快捷键如下：

  • Shift-Enter: 运行单元格 : 执行当前单元格，显示任何输出，并跳转到下面的下一个单元格。如果在最后一个单元格上调用 Shift-Enter，它会在下面创建一个新单元格。这相当于点击 单元格、运行 菜单项，或工具栏中的播放按钮。

  • Esc: 命令模式 : 在命令模式下，您可以使用键盘快捷键在笔记本文档中导航。

  • Enter: 编辑模式 : 在编辑模式下，您可以编辑单元格中的文本。

要查看所有可用快捷键的完整列表，请在笔记本文档菜单中点击 帮助、键盘快捷键。

搜索#

Jupyter Notebook 有一个高级的内置搜索插件，用于在笔记本文档或其他文档中查找文本，默认使用 Ctrl-F（macOS 为 Cmd+F）快捷键。

您的浏览器的 find 功能会给出意想不到的结果，因为它（默认情况下）无法访问文档的全部内容，但如果您愿意，仍然可以从浏览器菜单中使用浏览器的查找功能，或者您可以使用高级设置编辑器禁用内置搜索快捷键。

或者，您可以禁用窗口化笔记本文档渲染，以向浏览器公开完整的文档内容，但这会牺牲性能。

绘图#

Jupyter Notebook 的一个主要特点是能够显示运行代码单元格输出的图表。IPython 内核旨在与 [matplotlib] 绘图库无缝协作以提供此功能。特定的绘图库集成是内核的一个特性。

安装内核#

有关如何安装 Python 内核的信息，请参阅 IPython 安装页面。

Jupyter wiki 上有一长串其他语言的内核列表。它们通常附有关于如何在笔记本文档中启用该内核的说明。

信任笔记本文档#

为防止在打开笔记本文档时代表用户执行不受信任的代码，我们存储每个受信任笔记本文档的签名。笔记本文档服务器在打开笔记本文档时会验证此签名。如果找不到匹配的签名，Javascript 和 HTML 输出将不会显示，直到通过重新执行单元格重新生成它们。

任何您自己完全执行过的笔记本文档都将被视为受信任的，其 HTML 和 Javascript 输出将在加载时显示。

如果您需要在不重新执行的情况下查看 HTML 或 Javascript 输出，并且您确定该笔记本文档没有恶意，您可以在命令行中使用以下命令告诉 Jupyter 信任它：

$ jupyter trust mynotebook.ipynb

有关信任机制的更多详细信息，请参阅安全文档。

浏览器兼容性#

Jupyter Notebook 旨在支持这些浏览器的最新版本：

  • Chrome

  • Safari

  • Firefox

最新版本的 Opera 和 Edge 可能也可以工作，但如果它们不工作，请使用支持的浏览器之一。

已知在使用 HTTPS 和不受信任证书的 Safari 中无法正常工作（websockets 会失败）。