VS Code 中的 Jupyter Notebook

Jupyter（前身为 IPython Notebook）是一个开源项目，让你可以在一个被称为 notebook 的画布上轻松结合 Markdown 文本和可执行的 Python 源代码。Visual Studio Code 通过 Jupyter 扩展以及 Python 代码文件原生支持 Jupyter Notebook。本主题涵盖了 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 时，请确保你在受信任的工作区中工作。有害代码可能被嵌入到笔记本中，而 工作区信任 (Workspace Trust) 功能允许你指定哪些文件夹及其内容应允许或限制自动代码执行。

如果你尝试在 VS Code 处于非受信任工作区并运行 限制模式 (Restricted Mode) 时打开笔记本，你将无法执行代码单元，且富文本输出将被隐藏。

创建或打开 Jupyter Notebook

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

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

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

如果你已有 Jupyter Notebook，可以通过右键点击该文件并使用 VS Code 打开，或者通过 VS Code 文件资源管理器打开它。

运行代码单元

运行单个代码单元

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

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

运行多个代码单元

运行多个代码单元的方法有很多。你可以使用 Notebook 编辑器主工具栏中的双箭头运行笔记本中的所有单元，或者选择当前代码单元上方或下方的 运行所有 (Run All)、运行上方所有 (Run All Above) 或 运行下方所有 (Run All Below)。

运行部分代码单元

为了更轻松地运行笔记本中相关的单元，你可以使用 运行部分代码单元 (Run Cells in Section) 操作来运行通过 Markdown 分区标题归为一组的单元。此操作在 Notebook 大纲视图和粘性滚动 (Sticky Scroll) 元素中可用。

在粘性滚动元素中，右键点击你选择的标题，并通过上下文菜单中的操作运行该部分。在大纲视图中，选择悬停或选中时出现的工具栏图标，然后通过呈现的操作运行单个单元或一组单元。

保存 Jupyter Notebook

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

导出 Jupyter Notebook

你可以将 Jupyter Notebook 导出为 Python 文件 (.py)、PDF 或 HTML 文件。要导出，请选择主工具栏上的 ... > 导出 (Export)。然后会出现一个包含文件格式选项的下拉菜单。

注意：对于 PDF 导出，你必须安装 TeX。如果没有安装，当你选择 PDF 选项时，系统会通知你需要安装它。此外，请注意，如果你的笔记本中有仅 SVG 格式的输出，它们将不会显示在 PDF 中。要在 PDF 中显示 SVG 图形，请确保你的输出包含非 SVG 格式的图片，或者先导出为 HTML，然后使用浏览器保存为 PDF。

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

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

创建代码单元

默认情况下，空白笔记本会有一个空的代码单元供你开始，而已有的笔记本会在底部放置一个。将你的代码添加到空代码单元中即可开始。

msg = "Hello world"
print(msg)

代码单元模式

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

在命令模式下，单元左侧会出现一条实心垂直条。此时可以对单元进行操作，并接受键盘命令。

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

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

添加更多代码单元

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

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

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

选择代码单元

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

选择多个代码单元

要选择多个单元，先将一个单元置于选中模式。填充的背景表示选中的单元。要选择连续的单元，请按住 Shift 键并点击你想要选择的最后一个单元。要选择任意一组单元，请按住 Ctrl 键并点击你想要添加到选区的单元。

移动代码单元

你可以通过拖放操作在笔记本内上下移动单元。对于代码单元，拖放区域位于代码单元编辑器左侧，如下图所示。对于渲染后的 Markdown 单元，你可以点击任意位置进行拖放。

要移动多个单元，你可以使用选区中任一单元的相同拖放区域。

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

删除代码单元

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

撤销上一次更改

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

在代码和 Markdown 之间切换

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

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

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

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

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

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

启用/禁用行号

处于命令模式时，你可以使用 L 键启用或禁用单个代码单元内的行号。

要切换整个笔记本的行号显示，请在任何单元处于命令模式时使用 Shift+L。

目录

要浏览笔记本，请打开活动栏中的文件资源管理器。然后打开侧边栏中的 大纲 (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) 图标，你将看到当前变量列表，该列表会随着变量在代码中的使用而自动更新。变量窗格将在笔记本底部打开。

数据查看器

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

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

筛选行

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

如果你想查找精确匹配项，请在筛选条件前加上 '='。

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

保存绘图

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

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

自定义 Notebook 差异对比 (Diffing)

从底层实现来看，Jupyter Notebook 是 JSON 文件。JSON 文件中的片段被渲染为由三个组件组成的单元：输入、输出和元数据。使用基于行的差异对比来比较笔记本中的更改非常困难且难以解析。Notebook 的富文本差异对比编辑器允许你轻松查看单元每个组件的更改。

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

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

调试 Jupyter Notebook

有两种不同的方式来调试 Jupyter Notebook：一种是称为“逐行运行 (Run by Line)”的简易模式，另一种是完全调试模式。

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

逐行运行 (Run by Line)

“逐行运行”让你可以在不被其他 VS Code 调试功能干扰的情况下，逐行执行单元代码。要开始，请选择单元工具栏中的 逐行运行 (Run by Line) 按钮。

使用同一个按钮可以逐条语句推进。你可以选择单元 停止 (Stop) 按钮提前终止，或使用工具栏中的 继续 (Continue) 按钮继续运行直到单元结束。

调试单元 (Debug Cell)

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

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

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

在笔记本中搜索

你可以使用键盘快捷键 Ctrl/Cmd + F 在笔记本中进行搜索（或通过筛选搜索选项来搜索部分内容）。点击筛选选项（漏斗图标）以跨以下内容搜索：

• Markdown 单元输入 (Markdown Source)
• Markdown 单元输出 (Rendered Markdown)
• 代码单元输入 (Code Cell Source)
• 代码单元输出 (Cell Output)

默认情况下，笔记本搜索仅筛选单元输入。

连接到远程 Jupyter 服务器

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

要连接到远程 Jupyter 服务器：

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

   

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

   

3. 首次连接到现有服务器时，请选择 输入正在运行的 Jupyter 服务器的 URL (Enter the URL of the running Jupyter server)。

   

4. 当提示 输入正在运行的 Jupyter 服务器的 URL 时，请提供服务器的 URI（主机名）以及包含在 ?token= URL 参数中的身份验证令牌。（如果你在 VS Code 终端中启动服务器并启用了身份验证令牌，通常可以在终端输出中看到包含令牌的 URL，你可以从那里复制它。）或者，你也可以在提供 URI 后指定用户名和密码。

   

注意：为了增加安全性，微软建议通过 SSL 和令牌支持等安全预防措施来配置你的 Jupyter 服务器。这有助于确保发送到 Jupyter 服务器的请求经过身份验证，并且到远程服务器的连接是加密的。有关保护笔记本服务器的指南，请参阅 Jupyter 文档。

数据科学配置文件模板

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

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

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