在 VS Code 中试用

VS Code 中的 Jupyter Notebook

Jupyter(以前称为 IPython Notebook)是一个开源项目,可让您轻松地将 Markdown 文本和可执行 Python 源代码结合到称为 notebook 的一个画布上。Visual Studio Code 原生支持处理 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 文件。

工作区信任

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

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

创建或打开 Jupyter Notebook

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

Blank Jupyter Notebook

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

Kernel Picker

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

Language Picker

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

运行单元格

运行单个代码单元格

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

Run Jupyter code cell

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

运行多个代码单元格

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

Run multiple code cells

运行章节中的单元格

为了更轻松地运行 Notebook 中的相关单元格,您可以使用 运行章节中的单元格 操作运行通过 Markdown 章节标题分组的单元格。此操作可在 Notebook 大纲视图和 Sticky Scroll 元素上使用。

在 Sticky Scroll 元素中,右键单击您选择的标题,然后通过上下文菜单中的操作运行该章节。在大纲视图中,选择悬停或选中时出现的工具栏图标,然后通过呈现的操作运行单个单元格或一组单元格。

保存 Jupyter Notebook

您可以使用键盘快捷方式 Ctrl+S文件 > 保存 来保存您的 Jupyter Notebook。

导出 Jupyter Notebook

您可以将 Jupyter Notebook 导出为 Python 文件 (.py)、PDF 或 HTML 文件。要导出,请在主工具栏上选择 ... > 导出。然后会显示文件格式选项的下拉列表。

Convert Jupyter Notebook to Python file

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

在 Notebook 编辑器中使用代码单元格

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

创建代码单元格

默认情况下,空白 Notebook 将为您提供一个空代码单元格供您开始使用,现有 Notebook 则会在底部放置一个。将您的代码添加到空代码单元格即可开始。

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

移动代码单元格

您可以通过拖放的方式在 Notebook 中向上或向下移动单元格。对于代码单元格,拖放区域位于单元格编辑器的左侧,如下所示。对于已渲染的 Markdown 单元格,您可以在任何位置单击以拖放单元格。

Move a code cell

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

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

删除代码单元格

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

Delete a code cell

撤消上次更改

您可以使用 z 键撤消之前的更改,例如,如果您意外进行了编辑,可以将其撤消到之前正确的状态;如果您意外删除了一个单元格,可以恢复它。

在代码和 Markdown 之间切换

Notebook 编辑器允许您轻松地在 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 编辑器主工具栏来完成。

Notebook Toolbar

启用/禁用行号

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

Line numbers enabled in code cell

要切换整个 Notebook 的行号显示,在任何单元格处于命令模式时使用 Shift+L

Line numbers enabled for notebook

目录

要导航您的 Notebook,打开活动栏中的文件资源管理器。然后打开侧边栏中的 大纲 选项卡。

Table of contents

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

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

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

Jupyter Notebook 编辑器中的智能感知支持

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

IntelliSense support

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

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

Variable Explorer

Variable Explorer

数据查看器

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

Data Viewer

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

筛选行

在数据查看器中筛选行可以通过在每列顶部的文本框中输入来完成。输入您要搜索的字符串,将找到该列中包含该字符串的任何行

Data Viewer

如果您想查找完全匹配,请在您的筛选条件前加上 '='

Data Viewer

更复杂的筛选可以通过输入正则表达式来完成

Data Viewer

保存绘图

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

Save output

注意:支持渲染使用 matplotlibAltair 创建的绘图。

自定义 Notebook 差异比较

本质上,Jupyter Notebook 是 JSON 文件。JSON 文件中的片段被渲染为单元格,每个单元格由三个组件组成:输入、输出和元数据。使用基于行的差异比较 Notebook 中的更改既困难又难以解析。Notebook 的富差异比较编辑器使您可以轻松查看单元格每个组件的更改。

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

Custom notebook diffing

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

调试 Jupyter Notebook

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

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

按行运行

按行运行允许您一次执行单元格中的一行,而不会被其他 VS Code 调试功能分散注意力。要开始,请在单元格工具栏中选择 按行运行 按钮

Run by line button

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

调试单元格

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

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

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

Debug cell button

在 Notebook 中搜索

您可以使用键盘快捷方式 Ctrl/Cmd + F 在 Notebook 中(或通过筛选搜索选项来搜索部分内容)进行搜索。单击筛选器选项(漏斗图标)以跨以下内容进行搜索

  • Markdown 单元格输入 (Markdown 源)
  • Markdown 单元格输出 (已渲染的 Markdown)
  • 代码单元格输入 (代码单元格源)
  • 代码单元格输出 (单元格输出)

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

Search options

连接到远程 Jupyter 服务器

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

连接到远程 Jupyter 服务器

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

    Notebook kernel picker

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

    Select existing Jupyter server

  3. 首次连接现有服务器时,选择 输入正在运行的 Jupyter 服务器的 URL

    Choose to connect to an existing server

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

    Prompt to supply a Jupyter server URI

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

数据科学配置文件模板

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

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

Create Profile dropdown with profile templates

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