JupyterLab使用手册

Python

JupyterLab 是一款基于Web的交互式开发环境，它能够帮助开发者将代码、markdown、数据和其他元素整合在一个地方进行处理和展示，可以方便地编辑和运行Python等语言的代码。

JupyterLab界面

JupyterLab提供了灵活的交互式计算探索构建块。虽然JupyterLab具有许多传统集成开发环境（IDE）中的功能，但它仍然专注于交互式探索性计算。

JupyterLab界面包括一个主工作区，其中包含文档和活动的选项卡，可折叠的左侧边栏和菜单栏。左侧边栏包含文件浏览器、正在运行的内核和终端列表、命令调色板、笔记本单元格工具检查器以及选项卡列表。

Jupyter界面

JupyterLab会话始终驻留在工作区中。工作区包含JupyterLab的状态：当前打开的文件、应用程序区域和选项卡的布局等。工作区可以通过命名工作区URL在服务器上保存

菜单栏

JupyterLab 顶部的菜单栏有一级菜单，展示了 JupyterLab 中可用操作及其键盘快捷键。默认的菜单包括：

File：与文件和目录相关的操作
Edit：与文档编辑和其他活动相关的操作
View：改变 JupyterLab 外观的操作
Run：在不同活动中运行代码的操作，如笔记本和代码控制台
Kernel：管理内核的操作，内核是运行代码的独立进程
Tabs：停靠面板中打开的文档和活动列表
Settings：常见设置和高级设置编辑器
Help：JupyterLab 和内核帮助链接列表

JupyterLab 扩展还可以在菜单栏中创建新的一级菜单。

左右侧边栏

左侧边栏包括许多常用选项卡，包括：

文件浏览器，
主工作区的选项卡列表以及正在运行的内核和终端列表，
目录表，
扩展管理器。

JupyterLab 左侧边栏

右侧边栏包含：

属性检查器（在 notebooks 中处于活动状态），
调试器。

右侧边栏

在JupyterLab中，用于在标签之间切换的列称为Activity Bar。

可以通过在“View”菜单中选择“显示左侧边栏”或“显示右侧边栏”，或者单击活动边栏选项卡来折叠或展开侧边栏。

可以通过上下文菜单将选项卡的位置在左侧和右侧边栏之间切换。

JupyterLab扩展可以向侧边栏添加附加面板。

主工作区

JupyterLab中的主要工作区域可以将文档（笔记本、文本文件等）和其他活动（终端、代码控制台等）排列成选项卡面板，这些面板可以调整大小或细分。将选项卡拖到选项卡面板的中心即可将选项卡移动到该面板。通过将选项卡拖到面板的左侧、右侧、顶部或底部来将选项卡面板细分。

选项卡和简单界面模式

左侧边栏的选项卡面板列出主工作区中打开的文档或活动：

左侧边栏的选项卡

相同的信息也可以在选项卡菜单中找到：

通常情况下，将注意力集中在单个文档或活动上而不关闭主工作区中的其他标签页是很有用的。简易界面模式可以实现这一点，并且很容易返回到主工作区的多活动布局。使用“视图”菜单切换简易界面模式。

当您离开简易界面模式时，主区域的原始布局将被恢复。

上下文菜单

JupyterLab 的许多部分，比如笔记本、文本文件、代码控制台和选项卡，都有上下文菜单，可以通过右键单击元素来访问。通过按住Shift并右击，可以访问浏览器的本地上下文菜单。

键盘快捷键

与经典 notebook 一样，可以通过键盘快捷键浏览用户界面。您可以通过在设置菜单中选择“高级设置编辑器”项目，然后在设置选项卡中选择“键盘快捷键”，找到并自定义当前的键盘快捷键列表。

还可以通过在设置菜单中使用文本编辑器键映射子菜单，将文本编辑器自定义为使用vim、emacs或Sublime Text键盘映射。

JupyterLab URLs

与经典notebook类似，JupyterLab提供了一种让用户复制URL的方式，以打开特定的笔记本或文件。此外，JupyterLab URL是用户界面的高级部分，可以用于管理工作区。这两个功能 - 文件路径和工作区 - 可以组合在URL中，以打开特定工作区中的特定文件。

使用 /tree 进行文件导航¶

JupyterLab的文件导航URL采用了经典notebook的命名法；这些URL是/tree URLs：

http(s)://<server:port>/<lab-location>/lab/tree/path/to/notebook.ipynb

默认情况下，文件浏览器将导航到包含请求文件的目录。可以使用可选的file-browser-path查询参数更改此行为：

http(s)://<server:port>/<lab-location>/lab/tree/path/to/notebook.ipynb?file-browser-path=/

输入上述URL将在文件浏览器中显示工作区根目录，而不是/path/to/目录。

管理工作区（UI）

JupyterLab 会话始终驻留在一个工作区中。工作区包含 JupyterLab 的状态：当前打开的文件、应用程序区域和选项卡的布局等。当页面刷新时，将恢复工作区。

默认工作区没有名称，位于 /lab URL：

http(s)://<server:port>/<lab-location>/lab

所有其他工作区都有名称，是 URL 的一部分：

http(s)://server:port/<lab-location>/lab/workspaces/foo

工作区在服务器上保存其状态，并且只要用户（或浏览器）具有对同一服务器的访问权限，就可以在多个用户之间共享。

每次只能在单个浏览器选项卡中打开工作区。如果 JupyterLab 检测到同时打开多个工作区，则会提示输入新的工作区名称。

克隆工作区

可以使用克隆 URL 参数将一个工作区的内容复制到另一个工作区。

将工作区 foo 的内容复制到工作区 bar 中：

http(s)://server:port/<lab-location>/lab/workspaces/bar?clone=foo

将默认工作区的内容复制到工作区 foo：

http(s)://server:port/<lab-location>/lab/workspaces/foo?clone

将工作区 foo 的内容复制到默认工作区中：

http(s)://server:port/<lab-location>/lab?clone=foo

重置工作区

使用重置 URL 参数清除工作区的内容。

要重置工作区 foo 的内容：

http(s)://server:port/<lab-location>/lab/workspaces/foo?reset

要重置默认工作区的内容：

http(s)://server:port/<lab-location>/lab/workspaces/lab?reset

组合 URL 函数

这些 URL 函数可以如上所示单独使用，也可以组合使用。

要在重置工作区 foo 的内容后加载特定notebook：

http(s)://<server:port>/<lab-location>/lab/workspaces/foo/tree/path/to/notebook.ipynb?reset

将工作区 bar 的内容克隆到工作区 foo 并在其后加载notebook：

http(s)://<server:port>/<lab-location>/lab/workspaces/foo/tree/path/to/notebook.ipynb?clone=bar

重置默认工作区的内容并加载笔记本：

http(s)://<server:port>/<lab-location>/lab/tree/path/to/notebook.ipynb?reset

管理工作区（CLI）

JupyterLab 提供用于工作区导入和导出的命令行接口：

$ # 导出默认 JupyterLab 工作区
$ jupyter lab workspaces export
{"data": {}, "metadata": {"id": "/lab"}}
$
$ # 导出名为 `foo` 的工作区
$ jupyter lab workspaces export foo
{"data": {}, "metadata": {"id": "/lab/workspaces/foo"}}
$
$ # 将名为 `foo` 的工作区导出到名为 `file_name.json` 的文件中
$ jupyter lab workspaces export foo > file_name.json
$
$ # 导入名为 `file_name.json` 的工作区文件。
$ jupyter lab workspaces import file_name.json

导出时如果工作区不存在，则仍会生成一个空白工作区进行导出。

导入功能验证工作区文件的结构，并验证工作区元数据中的 id 字段，以确保其 URL 与 workspaces_url 配置或 page_url 配置兼容，以验证它是正确命名的工作区或者是默认工作区。

工作区文件格式

工作区文件是一个具有特定规范的 JSON 文件。

有两个顶级必须要有的key：data 和 metadata。

元数据必须是一个映射，其中包含一个 id 键，其值与工作区的 ID 相同。这也应该是访问工作区的相对 URL 路径，例如 /lab/workspaces/foo。

data 键映射到 IStateDB 的初始状态。许多插件在 State DB 中查找配置。还有任何注册到 ILayoutRestorer 的插件会在查找其跟踪器命名空间前面带有第一个 : 的所有键时进行查找。这些键的值应具有一个映射到 data 属性的数据。

例如，如果您的工作区如下所示：

{
  "data": {
    "application-mimedocuments:package.json:JSON": {
      "data": { "path": "package.json", "factory": "JSON" }
    }
  }
}

它将使用 { “path”: “package.json”, “factory”: “JSON” } 参数运行 docmanager:open，因为 application-mimedocuments 跟踪器已注册到 docmanager:open 命令中，如下所示：

const namespace = 'application-mimedocuments';
const tracker = new WidgetTracker<MimeDocument>({ namespace });
void restorer.restore(tracker, {
  command: 'docmanager:open',
  args: widget => ({
    path: widget.context.path,
    factory: Private.factoryNameProperty.get(widget)
  }),
  name: widget =>
    `${widget.context.path}:${Private.factoryNameProperty.get(widget)}`
});

请注意，第一个 : 后面的 data 键部分（package.json:JSON）被丢弃，并且是不相关的。

命令面板

JupyterLab 中的所有用户操作都通过集中式命令系统处理。这些命令在整个 JupyterLab 中共享和使用（菜单栏、上下文菜单、键盘快捷键等）。命令面板提供了一种基于键盘的方式来搜索并运行 JupyterLab 命令：

可以从“视图”菜单或使用键盘快捷键 Command/Ctrl Shift C 访问命令面板。

通过将“modal”: false 添加到设置中，可以在侧边栏中显示命令面板

调试器

JupyterLab 3.0 现在默认提供调试器前端。

这意味着可以直接从 JupyterLab 调试notebook、代码控制台和文件。

要求

要启用并显示调试器，需要具有支持调试的内核。

以下是已知支持 Jupyter 调试协议的内核列表：

xeus-python：Python 编程语言的 Jupyter 内核
xeus-robot：Robot Framework 的 Jupyter 内核
ipykernel：Jupyter 的 IPython 内核

其他 Jupyter 内核也可以通过实现 Jupyter Debugger 协议来支持调试并与 JupyterLab 调试器兼容。

如果您知道其他支持调试的内核，请打开 PR 将它们添加到此列表中。

以下是在新的 conda 环境中安装 ipykernel 和 xeus-python 的示例：

conda create -n jupyterlab-debugger -c conda-forge jupyterlab=3 "ipykernel>=6" xeus-python
conda activate jupyterlab-debugger

用法

对于 Python 来说，ipykernel（6.0+）和 xeus-python 都支持调试。

启用调试器，设置断点并进入代码：

一个 GIF 显示如何在内核中启用调试器。

教程笔记本

还有一个教程notebook可用于尝试调试器，位于 jupyter-ide-demo 存储库上，并且可以在 Binder 上运行。

如果在设置中将syncCollapseState属性设置为true，则目录和笔记本之间将同步。如果在目录中折叠标题，笔记本也会被折叠，同样地，在笔记本中展开单元格将展开目录。要执行此操作，请转到设置并单击高级设置编辑器，然后转到目录部分，并在用户首选项中添加syncCollapseState:true并保存设置。这里是一个演示它的动画。

单元格输出中的标题默认在目录和笔记本中编号。通过将设置includeOutput更改为false可以进行调整。要执行此操作，请转到设置，单击“高级设置编辑器”，然后转到“目录”部分，在“用户首选项”中添加includeOutput:false并保存设置。这里有一个演示其使用的动画。

设置

可以通过在JupyterLab的高级设置编辑器中设置的设置来修改扩展行为。

collapsibleNotebooks：启用从目录中折叠笔记本节的功能
numberingH1：如果设置为true，则对第一级标题（h1）进行编号
syncCollapseState：在目录和笔记本之间同步折叠行为
includeOutput：在笔记本和目录中包括输出编号。

扩展

JupyterLab本质上是一个可扩展的环境。 JupyterLab扩展可以自定义或增强JupyterLab的任何部分。它们可以提供新的主题、文件查看器和编辑器，或在笔记本中为丰富输出提供渲染器。扩展可以将项目添加到菜单或命令调色板、键盘快捷键或设置系统中。扩展可以为其他扩展提供API，并且可以依赖于其他扩展。实际上，整个JupyterLab本身只是一组扩展，它们没有比任何自定义扩展更强大或特权。

有关开发扩展的信息，请参见开发人员文档。

安装扩展

JupyterLab扩展包含安装到Jupyterlab并在浏览器中运行的JavaScript。扩展包含一个或多个插件，扩展JupyterLab功能。有两种类型的JupyterLab扩展：源扩展（安装时需要重新构建JupyterLab）和预构建扩展（不需要重新构建JupyterLab）。重建JupyterLab需要安装Node.js 。

JupyterLab扩展可以通过多种方式安装，包括：

Python pip或conda包可以包含源扩展或预构建扩展。这些包还可以包含用于扩展功能的必要服务器端组件。
在JupyterLab中的扩展管理器和jupyter labextension install命令可以从npm安装源扩展包。安装源扩展需要Node.js和JupyterLab重建以激活。请参见安装Node.js和使用jupyter labextension管理扩展。

安装Node.js

源扩展需要Node.js来重建JupyterLab并激活扩展。如果您使用conda-forge软件包，则可以使用以下代码获取Node.js：

conda install -c conda-forge nodejs

如果您使用默认的Anaconda软件包（即，您通常不使用conda-forge），则应使用以下代码从Anaconda默认通道安装Node.js：

conda install nodejs

您也可以从系统软件包管理器中获取Node.js，或者直接从Node.js网站下载并安装它。

使用jupyter labextension管理扩展

jupyter labextension命令使您能够安装或卸载npm中的源扩展、列出所有安装的扩展或禁用任何扩展。请参见jupyter labextension --help。

安装和卸载源扩展¶
您可以使用以下命令从npm安装源扩展：

jupyter labextension install my-extension my-other-extension

使用my-extension@version语法安装特定版本的扩展，例如：

jupyter labextension install my-extension@1.2.3

您还可以安装未上传到npm的源扩展，即my-extension可以是包含扩展的本地目录、压缩的tarball或指向压缩的tarball的URL。

注意：安装源扩展将需要安装Node.js并要求重建JupyterLab。

使用以下命令卸载源扩展：

jupyter labextension uninstall my-extension my-other-extension

如果您正在多个阶段安装/卸载几个扩展，您可能希望在安装/卸载步骤中包含–no-build标志以推迟重建JupyterLab。一旦准备好重建，可以运行以下命令：

jupyter lab build
注意：如果你在Windows上重新构建JupyterLab，由于Windows默认路径长度限制，你可能会遇到FileNotFoundError。Node模块存储在深度嵌套的目录结构中，因此路径可能非常长。如果你具有管理员权限并且使用的是Windows 8或10，可以按照这些说明更新注册表设置：https://stackoverflow.com/a/37528731。

启用和禁用扩展

禁用一个扩展会阻止 JupyterLab 中该扩展中所有插件的运行（尽管代码仍加载）。您可以通过以下命令禁用特定的 JupyterLab 扩展（包括核心扩展），而无需重新构建 JupyterLab：

jupyter labextension disable my-extension

您可以使用以下命令启用已禁用的扩展：

jupyter labextension enable my-extension

安装的扩展默认处于启用状态，除非有明确禁用它们的配置。扩展可以使用命令行禁用或启用。另一个扩展可以禁用扩展或扩展中的单个插件。

确定扩展是否启用或禁用的优先级顺序如下：

具有禁用扩展键的对象作为包名称的键和布尔值的 <jupyter_config_path>/labconfig/page_config.json 文件存在情况。
<lab_app_dir>/settings/page_config.json 中的 disabledExtensions 键的存在（已弃用）。该值是要禁用的扩展列表，但已被位于 labconfig 位置的分层配置方法取代。
另一个 JupyterLab 扩展的元数据中存在禁用给定扩展的 disabledExtensions 键。如果该扩展本身已禁用，则该键将被忽略。

在使用命令行时，可以针对配置的–level进行操作：用户、系统或sys-prefix（默认）。

例如，<jupyter_config_path>/labconfig/pageconfig.json 可能如下所示：

{
   "disabledExtensions": {
         "@jupyterlab/notebook-extension": true
   }
}

有关 LabConfig 目录的文档，请参见更多信息。

使用扩展管理器管理扩展程序

可以使用JupyterLab中的扩展管理器来管理作为npm上单个JavaScript包分发的扩展。

扩展管理器位于左侧边栏中。

默认视图有三个组件：搜索栏、“已安装”部分和“发现”部分。

免责声明

安装扩展程序允许其在服务器、内核和浏览器上执行任意代码。因此，我们要求您明确确认此点。

默认情况下，未确认免责声明。

图：用户未确认免责声明

由于未确认免责声明，您可以搜索扩展程序，但无法安装它（没有安装按钮可用）。

图：未确认免责声明，无法安装扩展

要安装扩展程序，您首先必须明确确认免责声明。完成后，它将跨会话保留，用户无需再次检查它。

图：已确认免责声明

为了方便使用，您可以隐藏免责声明，以便在屏幕上占用更少的空间。

图：免责声明已隐藏

查找扩展

您可以使用扩展管理器查找适用于JupyterLab的扩展。要在当前可用的扩展中自由发现，请展开“Discovery”部分。这会触发对NPM注册表上所有JupyterLab扩展的搜索，并根据注册表的排序顺序列出结果。此排序顺序的一个例外是，由Jupyter组织发布的扩展始终排在第一位。这些扩展通过其名称旁边的小型Jupyter图标来区分。

另外，您还可以使用搜索栏限制发现范围。这将在NPM注册表上执行JupyterLab扩展的自由文本搜索。

安装扩展

一旦找到了一个你认为有趣的源扩展，点击扩展列表条目中的“安装”按钮来安装它。

注意：安装扩展允许它在服务器、内核和客户端浏览器上执行任意代码。因此，您应该避免安装您不信任的扩展，并注意任何试图伪装成可信扩展的扩展。

安装扩展后不久，下拉菜单会出现在搜索栏下面，指示已下载扩展，但需要重新构建以完成安装。

屏幕截图显示重新构建指示器

如果您想安装/卸载其他扩展，可以忽略重建通知，直到您做出所有想要的更改。一旦满意，点击“重建”按钮开始后台重建。重建完成后，将弹出对话框，指示需要重新加载页面以将最新版本加载到浏览器中。

如果您忽略了重建通知，请刷新浏览器窗口以触发新的重建检查。

管理已安装的扩展

当有一些已安装的扩展时，它们将显示在“已安装”部分。然后可以卸载它们（如果它们是源扩展）或禁用它们。禁用扩展将防止其被激活，但不需要重新构建应用程序。

伴随包

在安装扩展时，JupyterLab将检查包元数据中是否有任何关于伴随包的指令。伴随包可以是：

notebook服务器扩展（或任何其他需要安装在笔记本服务器上的包）。
内核包。内核的伴随包示例是Jupyter Widget包，例如@jupyter-widgets/jupyterlab-manager包的ipywidgets Python包。

如果JupyterLab找到伴随包的指令，它将呈现对话框，通知您相关信息。这些仅作为信息提供，您可以选择是否考虑这些信息。

如果觉得文章对你有用，请随意赞赏

JupyterLab使用手册

https://xxlab.tech/archives/jupyterlab-shi-yong-shou-ce

作者

geekidentity

发布于

2023-04-14

更新于

2023-04-20

许可协议

CC BY 4.0