参加你附近的 ,了解 VS Code 中的 AI 辅助开发。

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 环境。要选择一个环境,请从命令面板(⇧⌘P (Windows, Linux Ctrl+Shift+P))中使用 Python: Select Interpreter 命令。

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

工作区信任

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

如果你尝试在受限模式下运行的非受信任工作区中打开 notebook,你将无法执行单元格,并且富文本输出将被隐藏。

创建或打开 Jupyter Notebook

你可以通过从命令面板(⇧⌘P (Windows, Linux Ctrl+Shift+P))运行 Create: New Jupyter Notebook 命令,或在你的工作区中创建一个新的 .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 大纲视图和粘性滚动元素中可用。

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

保存你的 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 编辑器中的 IntelliSense 支持

Python Jupyter Notebook 编辑器窗口具有完整的 IntelliSense 功能——代码补全、成员列表、方法的快速信息和参数提示。你在 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 的详细信息,请参阅此维基页面

逐行运行

逐行运行让你一次执行一个单元格的一行,而不会被其他 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 Source)
  • Markdown 单元格输出 (Rendered Markdown)
  • 代码单元格输入 (Code Cell Source)
  • 代码单元格输出 (Cell Output)

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

Search options

连接到远程 Jupyter 服务器

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

连接到远程 Jupyter 服务器:

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

    Notebook kernel picker

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

    Select existing Jupyter server

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

    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 建议为你的 Jupyter 服务器配置安全预防措施,例如 SSL 和令牌支持。这有助于确保发送到 Jupyter 服务器的请求经过身份验证,并且与远程服务器的连接是加密的。有关保护 notebook 服务器的指导,请参阅 Jupyter 文档

数据科学配置文件模板

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

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

Create Profile dropdown with profile templates

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