VS Code 中的 Jupyter Notebook

Jupyter（前身为 IPython Notebook）是一个开源项目，可让你在一个称为notebook的画布上轻松组合 Markdown 文本和可执行的 Python 源代码。Visual Studio Code 原生地（通过 Jupyter 扩展）支持处理 Jupyter Notebook，并通过 Python 代码文件支持。本主题涵盖了 Jupyter Notebook 的原生支持，并演示了如何

• 创建、打开和保存 Jupyter Notebook
• 处理 Jupyter 代码单元格
• 使用变量浏览器和数据查看器查看、检查和筛选变量
• 连接到远程 Jupyter 服务器
• 调试 Jupyter Notebook

设置你的环境

要使用 Jupyter Notebook 中的 Python，你必须在 VS Code 中激活 Anaconda 环境，或者激活已安装 Jupyter 包的另一个 Python 环境。要选择环境，请使用命令面板中的Python: Select Interpreter命令（⇧⌘P (Windows, Linux Ctrl+Shift+P)）。

激活适当的环境后，你可以创建和打开 Jupyter Notebook，连接到远程 Jupyter 服务器以运行代码单元格，并将 Jupyter Notebook 导出为 Python 文件。

环境变量

环境变量从 .env 文件加载。请参阅 Python 环境文档的该部分。

工作区信任

在开始使用 Jupyter Notebook 时，你需要确保你在一个受信任的工作区中工作。有害代码可能会嵌入到 Notebook 中，而 工作区信任功能允许你指示哪些文件夹及其内容应允许或限制自动代码执行。

如果你尝试在 VS Code 处于 受限模式的未受信任的工作区中打开 Notebook，你将无法执行单元格，并且富输出将被隐藏。

创建或打开 Jupyter Notebook

你可以通过从命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）运行Create: New Jupyter Notebook命令，或者在工作区中创建一个新的 .ipynb 文件来创建 Jupyter Notebook。

接下来，在右上角的内核选择器中选择一个内核。

选择内核后，每个代码单元格右下角的语言选择器将自动更新为内核支持的语言。

如果你有一个现有的 Jupyter Notebook，可以通过右键单击文件并选择“用 VS Code 打开”来打开它，或者通过 VS Code 文件资源管理器打开。

运行单元格

运行单个代码单元格

添加代码后，可以使用单元格左侧的Run图标运行单元格，输出将显示在代码单元格下方。

要运行选定的代码单元格，你也可以在命令模式和编辑模式下使用键盘快捷键。 Ctrl+Enter 运行当前选定的单元格。 Shift+Enter 运行当前选定的单元格并在下方立即插入一个新单元格（焦点移至新单元格）。 Alt+Enter 运行当前选定的单元格并在下方立即插入一个新单元格（焦点保留在当前单元格）。

运行多个代码单元格

可以通过多种方式运行多个代码单元格。你可以使用 Notebook 编辑器主工具栏中的双箭头运行 Notebook 中的所有单元格，或者通过选择当前代码单元格上方或下方的Run All、Run All Above或Run All Below来运行。

运行区域内的单元格

为了更轻松地运行 Notebook 中相关的单元格，你可以使用Run Cells in Section操作来运行由 Markdown 部分标题分组在一起的单元格。此操作在 Notebook 的大纲视图和 Sticky Scroll 元素中可用。

在 Sticky Scroll 元素中，右键单击你选择的标题，并通过上下文菜单中的操作来运行该区域。在大纲视图中，选择悬停或选择时出现的工具栏图标，然后通过提供的操作运行单个单元格或一组单元格。

保存你的 Jupyter Notebook

你可以使用键盘快捷键 Ctrl+S 或File > Save来保存你的 Jupyter Notebook。

导出你的 Jupyter Notebook

你可以将 Jupyter Notebook 导出为 Python 文件（.py）、PDF 或 HTML 文件。要导出，请在主工具栏上选择... > Export。然后，你将看到一个下拉列表，其中包含文件格式选项。

注意： 对于 PDF 导出，你必须安装 TeX。如果未安装，当你选择 PDF 选项时，会收到需要安装它的通知。另外，请注意，如果 Notebook 中只有 SVG 输出，它们将不会在 PDF 中显示。要在 PDF 中显示 SVG 图形，请确保你的输出包含非 SVG 图像格式，或者先导出到 HTML，然后使用浏览器将其保存为 PDF。

在 Notebook 编辑器中处理代码单元格

Notebook 编辑器可以轻松地在 Jupyter Notebook 中创建、编辑和运行代码单元格。

创建代码单元格

默认情况下，一个空白 Notebook 会有一个空的可用代码单元格供你开始，而一个现有的 Notebook 会在底部放置一个。将你的代码添加到空的可用代码单元格即可开始。

msg = "Hello world"
print(msg)

代码单元格模式

在处理代码单元格时，单元格可以处于三种状态：未选择、命令模式和编辑模式。代码单元格左侧的垂直条和编辑器边框显示了单元格的当前状态。当没有条形可见时，单元格处于未选择状态。当一个单元格被选中时，它可以处于命令模式或编辑模式。

在命令模式下，一个实心的垂直条将出现在单元格左侧。单元格可以被操作并接受键盘命令。

在编辑模式下，实心垂直条旁边会有一个围绕单元格编辑器的边框。单元格的内容（代码或 Markdown）可以被修改。

要切换模式，你可以使用键盘或鼠标。在键盘上，按 Enter 键进入编辑模式，或按 Esc 键进入命令模式。使用鼠标，单击代码单元格中单元格左侧的垂直条或代码/Markdown 区域外部。

添加额外的代码单元格

你可以使用主工具栏、单元格的添加单元格工具栏（悬停时可见）以及键盘命令来添加代码单元格。

要在新单元格添加到当前选定单元格下方，请使用主工具栏中的加号图标或单元格的悬停工具栏。

当代码单元格处于命令模式时，使用 A 键在选定单元格上方添加单元格，使用 B 键在选定单元格下方添加单元格。

选择代码单元格

你可以使用鼠标或键盘上的向上/向下箭头键来更改选定的代码单元格。当代码单元格处于命令模式时，你还可以使用 J 键（向下）和 K 键（向上）。

选择多个代码单元格

要选择多个单元格，从一个处于选择模式的单元格开始。填充的背景表示选定的单元格。要选择连续的单元格，请按住 Shift 键并单击你想要选择的最后一个单元格。要选择任何一组单元格，请按住 Ctrl 键并单击你想要添加到选择中的单元格。

移动代码单元格

你可以通过拖放来在 Notebook 中上下移动单元格。对于代码单元格，拖放区域位于单元格编辑器左侧，如下所示。对于渲染的 Markdown 单元格，你可以单击任意位置来拖放单元格。

要移动多个单元格，你可以使用包含在选择中的任何单元格的相同拖放区域。

键盘快捷键 Alt+Arrow 也可以移动一个或多个选定的单元格。

删除代码单元格

要删除代码，你可以使用代码单元格工具栏中的Delete图标。当选定的代码单元格处于命令模式时，你可以使用键盘快捷键 dd。

撤销上一次更改

你可以使用 z 键来撤销你之前的更改，例如，如果你进行了意外的编辑，你可以撤销到之前正确的状态，或者如果你意外删除了一个单元格，你可以恢复它。

在代码和 Markdown 之间切换

Notebook 编辑器让你能够轻松地在 Markdown 和代码之间更改代码单元格。选择单元格右下角的语言选择器将允许你在 Markdown 和（如果适用）所选内核支持的任何其他语言之间切换。

你也可以使用键盘来更改单元格类型。当一个单元格被选中且处于命令模式时，按 M 键将单元格类型切换为 Markdown，按 Y 键将单元格类型切换为代码。

一旦设置为 Markdown，你就可以在代码单元格中输入 Markdown 格式的内容。

要渲染 Markdown 单元格，你可以选择单元格工具栏中的复选标记，或者使用键盘快捷键 Ctrl+Enter 和 Shift+Enter。

清除输出或重启/中断内核

如果你想清除所有代码单元格的输出或重启/中断内核，你可以使用主 Notebook 编辑器工具栏来完成。

启用/禁用行号

当你在命令模式下时，你可以使用 L 键来启用或禁用单个代码单元格中的行号。

要切换整个 Notebook 的行号，请在任何单元格的命令模式下使用 Shift+L。

目录

要导航浏览你的 Notebook，请在活动栏中打开文件资源管理器。然后，在侧边栏中打开Outline选项卡。

你可以在大纲视图中使用筛选控件来包含 Markdown 标题、代码单元格和代码单元格符号。筛选器对应于以下设置

• notebook.outline.showMarkdownHeadersOnly
• notebook.outline.showCodeCells
• notebook.outline.showCodeCellSymbols

注意： 默认情况下，大纲只会显示 Markdown。要显示代码单元格，请启用以下设置：Notebook > Outline: Show Code Cells。

Jupyter Notebook 编辑器中的 IntelliSense 支持

Python Jupyter Notebook 编辑器窗口具有完整的 IntelliSense 功能——代码补全、成员列表、方法的快速信息和参数提示。你在 Notebook 编辑器窗口中的编码效率与在代码编辑器中一样高。

变量浏览器和数据查看器

在 Python Notebook 中，可以查看、检查、排序和筛选当前 Jupyter 会话中的变量。通过在运行代码和单元格后选择主工具栏中的Variables图标，你将看到当前变量的列表，该列表会随着变量在代码中的使用而自动更新。变量窗格将在 Notebook 的底部打开。

数据查看器

有关变量的更多信息，你还可以双击一行或使用变量旁边的Show variable in data viewer按钮在数据查看器中查看变量的详细信息。

或者，你也可以使用其他扩展提供的诸如 Data Wrangler 等扩展提供的数据查看体验。Data Wrangler 扩展提供了一个丰富的用户界面来显示你的数据的见解，并帮助你执行数据分析、质量检查、转换等操作。在我们的文档中了解有关 Data Wrangler 扩展的更多信息。

筛选行

可以通过在每列顶部的文本框中键入来筛选数据查看器中的行。键入你要搜索的字符串，任何在该列中包含该字符串的行都将被找到。

如果你想找到精确匹配，请在你的筛选器前加上 '='

通过键入 正则表达式可以进行更复杂的筛选。

保存绘图

要保存 Notebook 中的绘图，只需将鼠标悬停在输出上，然后选择右上角的Save图标。

注意： 支持渲染使用 matplotlib 和 Altair 创建的绘图。

自定义 Notebook 差异比较

在底层，Jupyter Notebook 是 JSON 文件。JSON 文件中的片段被渲染为单元格，这些单元格由三个组件组成：输入、输出和元数据。使用基于行的差异比较 Notebook 中的更改是困难且难以解析的。Notebook 的富差异比较编辑器可让你轻松查看单元格每个组件的更改。

你甚至可以自定义要在差异视图中显示的更改类型。在右上角的工具栏中选择溢出菜单项，以自定义要包含的单元格组件。输入差异将始终显示。

要了解有关 VS Code 中 Git 集成的更多信息，请访问 VS Code 中的源代码管理。

调试 Jupyter Notebook

有两种不同的方法可以调试 Jupyter Notebook：一种称为“逐行运行”的简单模式，以及完整的调试模式。

注意： 这两个功能都需要 ipykernel 6+。有关安装或升级 ipykernel 的详细信息，请参阅 此 wiki 页面。

逐行运行

逐行运行允许你一次执行一个单元格的一行代码，而不会被 VS Code 的其他调试功能分心。要开始，请选择单元格工具栏中的Run by Line按钮。

使用相同的按钮按语句前进。你可以选择单元格的Stop按钮提前停止，或者选择工具栏中的Continue按钮继续运行到单元格的末尾。

调试单元格

如果你想使用 VS Code 支持的全部调试功能，例如断点以及能够单步进入其他单元格和模块，你可以使用完整的 VS Code 调试器。

1. 首先，通过单击 Notebook 单元格左边距来设置任何需要的断点。
2. 然后，选择菜单中Run按钮旁边的Debug Cell按钮。这将会在调试会话中运行单元格，并在你设置的任何断点处暂停，即使代码在不同的单元格或 .py 文件中。
3. 你可以像在 VS Code 中一样使用调试视图、调试控制台和调试工具栏中的所有按钮。

请注意，调试 Jupyter Notebook 中的单元格不使用 launch.json 中的任何调试配置。相反，可以通过诸如 jupyter.debugJustMyCode 等设置进行自定义。

搜索 Notebook

你可以使用键盘快捷键 Ctrl/Cmd + F 搜索 Notebook（或其部分，通过筛选搜索选项）。单击 Filter 选项（漏斗图标）以跨越以下内容进行搜索：

• Markdown 单元格输入（Markdown Source）
• Markdown 单元格输出（Rendered Markdown）
• 代码单元格输入（Code Cell Source）
• 代码单元格输出（Cell Output）

默认情况下，Notebook 搜索仅筛选单元格输入。

连接到远程 Jupyter 服务器

通过连接到远程 Jupyter 服务器，你可以将 Jupyter Notebook 中的密集计算卸载到其他计算机上。连接后，代码单元格将在远程服务器而不是本地计算机上运行。

连接到远程 Jupyter 服务器

1. 打开 Notebook 右上角的内核选择器按钮（或从命令面板运行Notebook: Select Notebook Kernel命令）。

   

2. 选择Existing Jupyter Server选项以连接到现有的 Jupyter 服务器。

   

3. 要首次连接到现有服务器，请选择Enter the URL of the running Jupyter server。

   

4. 当提示输入Enter the URL of the running Jupyter server时，提供服务器的 URI（主机名），并附带包含在 ?token= URL 参数中的身份验证令牌。（如果你在 VS Code 终端中启动服务器并启用了身份验证令牌，则通常会在终端输出中显示带令牌的 URL，你可以从那里复制。）或者，在提供 URI 后，你可以指定用户名和密码。

   

注意： 为增强安全性，Microsoft 建议配置你的 Jupyter 服务器时采取安全措施，例如 SSL 和令牌支持。这有助于确保发送到 Jupyter 服务器的请求经过身份验证，并且到远程服务器的连接已加密。有关保护 Notebook 服务器的指南，请参阅 Jupyter 文档。

数据科学配置文件模板

配置文件可让你根据当前项目或任务快速切换扩展、设置和 UI 布局。为了帮助你开始使用 Jupyter Notebook，你可以使用 数据科学配置文件模板，这是一个精选的配置文件，其中包含有用的扩展、设置和代码片段。你可以直接使用配置文件模板，也可以将其作为起点，根据自己的工作流进行进一步自定义。

您通过“**配置文件**”>“**创建配置文件...**”下拉菜单选择一个配置文件模板

一旦你选择了一个配置文件模板，你可以审查其设置和扩展，并且如果你不想将某些项包含在新配置文件中，可以单独移除它们。基于模板创建新配置文件后，对设置、扩展或 UI 所做的更改将持久化在你的配置文件中。