现已推出!阅读 10 月份的新功能和修复。

VS Code 中的 Jupyter 笔记本

Jupyter(以前称为 IPython Notebook)是一个开源项目,它允许您轻松地在称为 **笔记本** 的一个画布上组合 Markdown 文本和可执行的 Python 源代码。Visual Studio Code 本机支持使用 Jupyter 笔记本,并通过 Python 代码文件 支持。本主题涵盖了 Jupyter 笔记本的本机支持,并演示了如何

  • 创建、打开和保存 Jupyter 笔记本
  • 使用 Jupyter 代码单元格
  • 使用变量资源管理器和数据查看器查看、检查和筛选变量
  • 连接到远程 Jupyter 服务器
  • 调试 Jupyter 笔记本

设置环境

要在 Jupyter 笔记本中使用 Python,您必须在 VS Code 中激活 Anaconda 环境,或激活您已安装 Jupyter 包 的另一个 Python 环境。要选择环境,请使用命令面板(⇧⌘P(Windows、Linux Ctrl+Shift+P))中的 **Python:选择解释器** 命令。

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

工作区信任

在开始使用 Jupyter 笔记本时,您需要确保在受信任的工作区中工作。笔记本中可能嵌入有害代码,并且 工作区信任 功能允许您指示哪些文件夹及其内容应该允许或限制自动代码执行。

如果您在 VS Code 处于运行 受限模式 的不受信任的工作区时尝试打开笔记本,您将无法执行单元格,并且丰富的输出将被隐藏。

创建或打开 Jupyter 笔记本

您可以通过运行命令面板(⇧⌘P(Windows、Linux Ctrl+Shift+P))中的 **创建:新 Jupyter 笔记本** 命令,或在工作区中创建新的 .ipynb 文件来创建 Jupyter 笔记本。

Blank Jupyter Notebook

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

Kernel Picker

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

Language Picker

如果您有现有的 Jupyter 笔记本,您可以通过右键单击该文件并使用 VS Code 打开它,或者通过 VS Code 文件资源管理器打开它。

运行单元格

运行单个代码单元格

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

Run Jupyter code cell

要运行选定的代码单元格,您也可以在命令模式和编辑模式下使用键盘快捷键。Ctrl+Enter 运行当前选定的单元格。 Shift+Enter 运行当前选定的单元格并在其下方插入一个新单元格(焦点移动到新单元格)。Alt+Enter 运行当前选定的单元格并在其下方插入一个新单元格(焦点保留在当前单元格上)。

运行多个代码单元格

运行多个代码单元格可以通过多种方式实现。您可以使用笔记本编辑器主工具栏中的双箭头运行笔记本中的所有单元格,或者选择当前代码单元格上方或下方的 **运行全部**、**运行全部上方** 或 **运行全部下方**。

Run multiple code cells

运行部分中的单元格

为了更容易地运行笔记本中相关联的单元格,您可以运行由 Markdown 部分标题分组在一起的单元格,方法是使用 **运行部分中的单元格** 操作。此操作在笔记本大纲视图和粘性滚动元素中可用。

在粘性滚动元素中,右键单击您选择的部分标题,并通过上下文菜单中的操作运行该部分。在概述视图中,选择悬停或选中时出现的工具栏图标,然后通过显示的操作运行单个单元格或部分单元格。

保存 Jupyter 笔记本

您可以使用键盘快捷键 Ctrl+S 或 **文件** > **保存** 保存 Jupyter 笔记本。

导出 Jupyter 笔记本

您可以将 Jupyter 笔记本导出为 Python 文件 (.py)、PDF 或 HTML 文件。要导出,请在主工具栏上选择 **...** > **导出**。然后,您将看到一个包含文件格式选项的下拉菜单。

Convert Jupyter Notebook to Python file

**注意:** 对于 PDF 导出,您必须 安装 TeX。如果您没有,您会在选择 PDF 选项时收到通知,说明您需要安装它。此外,请注意,如果您的笔记本中只有 SVG 输出,它们将不会在 PDF 中显示。要在 PDF 中拥有 SVG 图形,请确保您的输出包含非 SVG 图像格式,或者您可以先导出到 HTML,然后使用浏览器将其保存为 PDF。

在笔记本编辑器中使用代码单元格

笔记本编辑器使您能够轻松地在 Jupyter 笔记本中创建、编辑和运行代码单元格。

创建代码单元格

默认情况下,空白笔记本将包含一个空的代码单元格供您开始使用,而现有笔记本将在底部放置一个代码单元格。将您的代码添加到空的代码单元格以开始使用。

msg = "Hello world"
print(msg)

Simple Jupyter code cell

代码单元格模式

在使用代码单元格时,单元格可以处于三种状态:未选中、命令模式和编辑模式。代码单元格左侧和编辑器边框的垂直栏显示单元格的当前状态。当没有可见的栏时,单元格未选中。当单元格选中时,它可以处于命令模式或编辑模式。

Unselected Jupyter code cell

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

Code cell in command mode

在编辑模式下,实心垂直栏与代码单元格编辑器周围的边框相连。单元格的内容(代码或 Markdown)可以被修改。

Code cell in edit mode

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

添加额外的代码单元格

您可以使用主工具栏、单元格的添加单元格工具栏(悬停可见)以及键盘命令添加代码单元格。

Add code cells

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

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

选择代码单元格

您可以使用鼠标或键盘上的上/下箭头键更改选定的代码单元格。当代码单元格处于命令模式时,您也可以使用 J 键(向下)和 K 键(向上)。

选择多个代码单元格

要选择多个单元格,请先选中一个单元格。已选中的单元格将显示填充的背景。若要选择连续的单元格,请按住 Shift 键并单击要选择的最后一个单元格。若要选择任意单元格组,请按住 Ctrl 键并单击要添加到选定内容中的单元格。

Multiselected cells

移动代码单元格

您可以通过拖放操作在笔记本中上下移动单元格。对于代码单元格,拖放区域位于单元格编辑器的左侧,如下所示。对于已呈现的 Markdown 单元格,您可以单击任意位置以拖放单元格。

Move a code cell

若要移动多个单元格,您可以使用选择内容中任何单元格的相同拖放区域。

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

删除代码单元格

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

Delete a code cell

撤消上一次更改

您可以使用 z 键撤消上一次更改,例如,如果您不小心进行了编辑,可以将其撤消到上一个正确状态,或者如果您不小心删除了单元格,可以将其恢复。

在代码和 Markdown 之间切换

笔记本编辑器允许您轻松地在 Markdown 和代码之间更改代码单元格。选择单元格右下角的语言选择器,可以切换到 Markdown,以及(如果适用)选定内核支持的任何其他语言。

Change language

您也可以使用键盘更改单元格类型。当单元格被选中并处于命令模式时,M 键将单元格类型切换到 Markdown,而 Y 键将单元格类型切换到代码。

设置 Markdown 后,您可以将 Markdown 格式的内容输入代码单元格。

Raw Markdown displayed in code cell

若要呈现 Markdown 单元格,您可以选择单元格工具栏中的复选标记,或使用键盘快捷键 Ctrl+EnterShift+Enter

How to render Markdown

Rendered Markdown displayed in code cell

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

如果您想清除所有代码单元格输出或重新启动/中断内核,可以使用主笔记本编辑器工具栏来完成。

Notebook Toolbar

启用/禁用行号

当您处于命令模式时,可以使用 L 键在一个代码单元格内启用或禁用行号。

Line numbers enabled in code cell

若要切换整个笔记本的显示行号,请在任何单元格的命令模式下使用 Shift+L

Line numbers enabled for notebook

目录

若要浏览笔记本,请在活动栏中打开文件资源管理器。然后打开侧边栏中的 **大纲** 选项卡。

Table of contents

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

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

**注意:** 默认情况下,大纲只显示 Markdown。若要显示代码单元格,请启用以下设置:**笔记本 > 大纲:显示代码单元格**。

Jupyter 笔记本编辑器中的 IntelliSense 支持

Python Jupyter Notebook 编辑器窗口具有完整的 IntelliSense - 代码完成、成员列表、方法的快速信息和参数提示。您在 Notebook 编辑器窗口中输入代码时的效率与在代码编辑器中一样高。

IntelliSense support

变量资源管理器和数据查看器

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

Variable Explorer

Variable Explorer

数据查看器

有关变量的更多信息,您还可以双击一行或使用变量旁边的 **在数据查看器中显示变量** 按钮来更详细地查看数据查看器中的变量。

Data Viewer

或者,您可以使用其他扩展提供的查看数据体验,例如 数据整理程序。数据整理程序扩展提供了一个丰富的用户界面来显示有关数据的见解,并帮助您执行数据分析、质量检查、转换等等。了解更多关于 我们的文档中的数据整理程序扩展

筛选行

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

Data Viewer

如果您想查找完全匹配,请在过滤器前缀中添加 '='

Data Viewer

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

Data Viewer

保存绘图

要从笔记本保存绘图,只需将鼠标悬停在输出上,然后选择右上角的 **保存** 图标即可。

Save output

**注意:** 支持呈现使用 matplotlibAltair 创建的绘图。

自定义笔记本差异

在幕后,Jupyter Notebook 是 JSON 文件。JSON 文件中的段将被呈现为包含三个组件的单元格:输入、输出和元数据。使用基于行的差异比较笔记本中所做的更改很困难,而且难以解析。笔记本的丰富差异编辑器允许您轻松地查看每个单元格组件的更改。

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

Custom notebook diffing

若要详细了解 VS Code 中的 Git 集成,请访问 VS Code 中的源代码管理

调试 Jupyter 笔记本

有两种不同的方法可以调试 Jupyter Notebook:一种称为“按行运行”的简化模式,以及完整的调试模式。

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

按行运行

按行运行允许您一次执行一行单元格,而不会受到其他 VS Code 调试功能的干扰。要开始,请在单元格工具栏中选择 **按行运行** 按钮

Run by line button

使用同一个按钮前进一个语句。您可以选择单元格 **停止** 按钮提前停止,或者选择工具栏中的 **继续** 按钮继续运行到单元格末尾。

调试单元格

如果您想使用 VS Code 支持的完整调试功能集,例如断点和能够逐步进入其他单元格和模块,您可以使用完整的 VS Code 调试器。

  1. 首先通过单击笔记本单元格的左侧边距来设置所需的任何断点。
  2. 然后选择 **运行** 按钮旁边的菜单中的 **调试单元格** 按钮。这将运行单元格中的调试会话,并在运行的任何代码中(即使是在其他单元格或 .py 文件中)的断点处暂停。
  3. 您可以像在 VS Code 中一样使用调试视图、调试控制台以及调试工具栏中的所有按钮。

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

Debug cell button

在笔记本中搜索

您可以通过使用键盘快捷键 Ctrl/Cmd + F 在笔记本(或通过过滤搜索选项来搜索部分笔记本)中搜索。单击筛选选项(漏斗图标)以搜索以下内容

  • Markdown 单元格输入(**Markdown 源代码**)
  • Markdown 单元格输出(**已呈现的 Markdown**)
  • 代码单元格输入(**代码单元格源代码**)
  • 代码单元格输出(**单元格输出**)

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

Search options

连接到远程 Jupyter 服务器

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

要连接到远程 Jupyter 服务器

  1. 打开笔记本右上角的内核选择器按钮(或从命令面板运行 **笔记本:选择笔记本内核** 命令)。

    Notebook kernel picker

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

    Select existing Jupyter server

  3. 要首次连接到现有服务器,请选择 **输入正在运行的 Jupyter 服务器的 URL**。

    Choose to connect to an existing server

  4. 当系统提示您 **输入正在运行的 Jupyter 服务器的 URL** 时,请提供服务器的 URI(主机名),其中包含包含 ?token= URL 参数的身份验证令牌。(如果您在 VS Code 终端中使用身份验证令牌启动服务器,则包含令牌的 URL 通常会显示在您从中可以复制它的终端输出中。)或者,您可以在提供 URI 后指定用户名和密码。

    Prompt to supply a Jupyter server URI

**注意:** 为了增加安全性,Microsoft 建议您使用安全预防措施(如 SSL 和令牌支持)配置 Jupyter 服务器。这有助于确保发送到 Jupyter 服务器的请求经过身份验证,并且与远程服务器的连接是加密的。有关保护笔记本服务器的指南,请参阅 Jupyter 文档

数据科学配置文件模板

配置文件 允许您根据当前项目或任务快速切换扩展、设置和 UI 布局。为了帮助您开始使用 Jupyter Notebook,您可以使用 数据科学配置文件模板,它是一个经过精心策划的配置文件,包含有用的扩展、设置和代码段。您可以按原样使用配置文件模板,也可以将其用作起点,以便根据自己的工作流程进行进一步自定义。

您可以通过 **配置文件** > **创建配置文件...** 下拉菜单选择配置文件模板

Create Profile dropdown with profile templates

选择配置文件模板后,您可以查看设置和扩展,并删除您不想包含在新的配置文件中的单个项目。根据模板创建新的配置文件后,对设置、扩展或 UI 所做的更改将保留在您的配置文件中。