扩展#

从根本上说，JupyterLab 被设计为一个可扩展的环境。JupyterLab 扩展可以定制或增强 JupyterLab 的任何部分。它们可以提供新的主题、文件查看器和编辑器，或笔记本中富输出的渲染器。扩展可以向菜单或命令面板添加项目、键盘快捷键，或设置系统中的设置。扩展可以为其他扩展提供 API 以供使用，并且可以依赖于其他扩展。事实上，整个 JupyterLab 本身只是一个扩展的集合，它们并不比任何自定义扩展更强大或更具特权。

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

安装扩展 #

JupyterLab 扩展包含安装到 JupyterLab 并在浏览器中运行的 JavaScript。一个扩展包含一个或多个扩展 JupyterLab 的插件。首选的 JupyterLab 扩展类型是“预构建扩展”，因为它不需要重新构建 JupyterLab JavaScript 文件。

大多数 JupyterLab 扩展可以使用 Python pip 或 conda 包安装。这些包也可能包含扩展功能所需的服务器端组件。

在 PyPI 上浏览扩展#

Python Package Index (PyPI) 是 Python 编程语言的软件存储库，也是 pip 包管理器的默认包源。虽然简单的文本搜索会显示数百个包，但有许多分类器可供包自我描述所提供的功能和兼容性

注意

这些分类器于 2021 年 8 月初被接受，它们的广泛采用需要一些时间。

你可以帮忙！向包的 setup.py、setup.cfg 或 pyproject.toml 提议分类器可以构成一个很棒的首次开源贡献，因为这些贡献是

对你来说很容易，通常可以直接通过项目源代码网站（例如 GitHub 或 GitLab）进行，
对维护者来说很容易审查和合并，并且
可以对包的可发现性产生积极影响

使用扩展管理器管理扩展 #

您可以使用 JupyterLab 中的扩展管理器来管理扩展。出于安全原因，此功能可能已被您的系统管理员禁用。

注意

自 JupyterLab v4 以来，默认管理器使用 PyPI.org 作为可用扩展的来源，并使用 pip 安装它们。

如果 Python 包具有分类器：框架 :: Jupyter :: JupyterLab :: 扩展 :: 预构建，则会列出该扩展。

此外，建议扩展作者提供 install.json 文件以指定确切的 Python 包名称。

警告

没有检查以确保扩展与当前的 JupyterLab 版本兼容。

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

../_images/extensions-default.png — 图：默认视图包含三个组件：搜索栏、“已安装”部分和“发现”部分。#

免责声明#

危险

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

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

../_images/extensions-disabled.png — 图：用户尚未确认免责声明#

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

要安装扩展，您必须首先明确确认免责声明。一旦完成，这将保留在会话之间，用户无需再次检查。

../_images/extensions-enabled.png — 图：免责声明已选中#

为了便于使用，您可以折叠免责声明，使其在屏幕上占用更少的空间。

查找扩展#

您可以使用扩展管理器查找 JupyterLab 的扩展。要浏览当前可用的扩展，请展开“发现”部分。这将触发对 PyPI.org 注册表上所有 JupyterLab 扩展的搜索，结果按字母顺序列出。

或者，您可以使用搜索栏限制您的发现。这将对 PyPI.org 注册表上的 JupyterLab 扩展执行自由文本搜索。

An example search result in the discovery extension listing.

安装扩展#

一旦您找到一个您认为有趣的扩展，通过单击扩展列表条目的“安装”按钮来安装它。

危险

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

新安装的扩展可能需要重新启动 JupyterLab。

管理已安装的扩展#

当安装了一些扩展时，它们将显示在“已安装”部分。然后可以卸载或禁用它们。禁用扩展将阻止它被激活，但无需重新构建应用程序。

配置扩展管理器#

默认情况下，JupyterLab 提供两个扩展管理器

pypi：[默认] 允许从 PyPI.org 安装/卸载扩展
readonly：显示已安装的扩展（具有禁用/启用它们的能力）

您可以使用命令行选项 --LabApp.extension_manager 指定管理器；例如，要使用只读管理器

jupyter lab --LabApp.extension_manager=readonly

PyPI 管理器设置#

pypi 管理器具有可以通过命令行选项设置的特定选项

--PyPIExtensionManager.base_url：PyPI 仓库基础 URL - 默认为 https://pypi.ac.cn/pypi。
--PyPIExtensionManager.rpc_request_throttling：对 PyPI XML-RPC API 请求之间的限制时间（秒） - 默认 1。
--PyPIExtensionManager.cache_timeout：PyPI 扩展列表缓存超时（秒） - 默认 300。
--PyPIExtensionManager.package_metadata_cache_size：包元数据缓存大小 - 默认 1500。

列表#

在扩展管理器中搜索扩展时，JupyterLab 会显示完整的搜索结果，用户可以自由安装任何源扩展。这是默认模式。

为了提高安全性，您或您的管理员可以启用 blocklists 或 allowlists 模式。JupyterLab 将根据定义的列表检查扩展。

警告

一次只允许一种模式。如果您或您的服务器管理员同时配置了黑名单和白名单，则白名单优先。

以下详细说明了黑名单模式和白名单模式的行为。启用配置列表的详细信息可以在列表配置中阅读。

默认模式#

在 default 模式下，未启用任何列表，搜索行为不变，与之前描述的相同。

黑名单模式#

扩展可以自由下载，而无需经过审查过程。但是，用户可以将恶意扩展添加到黑名单。扩展管理器将显示所有扩展，除了那些已明确添加到黑名单的扩展。因此，扩展管理器不允许您安装黑名单扩展。

如果您或您的管理员已启用黑名单模式，JupyterLab 将使用黑名单并从您的搜索结果中删除所有黑名单扩展。

如果您在扩展被列入黑名单之前安装了它，则已安装列表中的扩展条目将以红色突出显示。建议您卸载它。您可以将鼠标移到问号图标上以阅读说明。

../_images/extensions-blocked-list.png — 图：已被列入黑名单的已安装扩展，应将其删除#

白名单模式#

白名单维护了一组用户可以自由搜索和安装的经批准的扩展。扩展在添加到白名单之前需要经过某种审查过程。使用白名单时，扩展管理器将只显示已明确添加到白名单的扩展。

如果您或您的管理员已启用白名单模式，JupyterLab 将使用白名单并只显示白名单中存在的扩展。其他扩展将不会显示在搜索结果中。

如果您安装了一个白名单扩展，并且在某个时间点该扩展从白名单中删除，则已安装列表中的扩展条目将以红色突出显示。建议您卸载它。您可以将鼠标移到问号图标上以阅读说明。

../_images/extensions-allowed-list.png — 图：第二个已安装的扩展已从白名单中删除，应将其删除#

列表配置#

您或您的管理员可以使用以下特性来定义列表加载。

blocked_extensions_uris：逗号分隔的 URI 列表，用于从中获取黑名单文件
allowed_extensions_uris：逗号分隔的 URI 列表，用于从中获取白名单文件
listings_refresh_seconds：刷新列表的间隔延迟（秒）
listings_tornado_options：用于列表 HTTP 请求的可选 kwargs

例如，要设置被阻止的扩展，请使用 --LabServerApp.blocked_extensions_uris=http://example.com/blocklist.json 启动服务器，其中 http://example.com/blocklist.json 是一个 JSON 文件，如下所述。

listings_tornado_options 的详细信息列在此页面上（例如，您可以传递 {'request_timeout': 10} 以更改 HTTP 请求超时值）。

列表是托管在您给定的 URI 上的 JSON 文件。

对于每个条目，您必须定义扩展在 NPM 注册表中发布的名称。name 属性支持正则表达式。

（可选）您还可以为您的记录添加更多字段（type、reason、creation_date、last_update_date）。这些可选字段未在用户界面中使用。

这是一个黑名单文件的示例。

{
  "blocked_extensions": [
    {
      "name": "@jupyterlab-examples/launcher",
      "type": "jupyterlab",
      "reason": "@jupyterlab-examples/launcher is blocklisted for test purpose - Do NOT take this for granted!!!",
      "creation_date": "2020-03-11T03:28:56.782Z",
      "last_update_date":  "2020-03-11T03:28:56.782Z"
    }
  ]
}

在以下允许的扩展中，@jupyterlab/* 将允许所有 jupyterlab 组织扩展。

{
  "allowed_extensions": [
    {
      "name": "@jupyterlab/*",
      "type": "jupyterlab",
      "reason": "All @jupyterlab org extensions are allowed, of course…",
      "creation_date": "2020-03-11T03:28:56.782Z",
      "last_update_date":  "2020-03-11T03:28:56.782Z"
    }
  ]
}

使用插件管理器管理插件 #

每个 JupyterLab 扩展都由一个或多个插件组成。JupyterLab 核心本身也使用插件。

高级插件管理器可以列出和禁用单个插件，但可能已被您的系统管理员禁用。

在功能上，从插件管理器切换扩展相当于运行 jupyter labextension enable 或 jupyter labextension disable 命令。

An example search result in the plugin extension listing.

插件可以在 system、sys-prefix（默认）或 user 级别启用/禁用，这会影响 page_config.json 配置文件写入的位置（参见 jupyter --paths 结果中的 config 部分）。要更改插件管理器和默认扩展管理器的级别，请使用 PluginManager.level 特性（扩展管理器继承自插件管理器）。

锁定和解锁插件#

管理员可以使用以下方式锁定特定插件

jupyter labextension lock my-extension:plugin

解锁锁定的插件

jupyter labextension unlock my-extension:plugin

锁定的插件在插件列表中显示一个锁定图标，无法从用户界面启用/禁用

An example row of the plugin list with `@jupyterlab/pluginmanager-extension:plugin` plugin locked.

使用 `jupyter labextension` 管理扩展 #

jupyter labextension 命令使您能够列出所有已安装的扩展，或禁用任何扩展。它还为开发人员带来了帮助命令。请参阅 jupyter labextension --help 以获取帮助。

列出已安装的扩展#

使用以下命令列出所有已安装的扩展

jupyter labextension list

注意

jupyter labextension 通过其插件命名空间（冒号 : 之前的部分）标识扩展，这可能与用于分发扩展的 pip 或 conda 包的名称不同。

启用和禁用扩展#

禁用扩展会阻止该扩展中的所有插件在 JupyterLab 中运行（尽管代码仍然加载）。您也可以禁用特定的 JupyterLab 扩展（包括核心扩展）

jupyter labextension disable my-extension

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

jupyter labextension enable my-extension

默认情况下，已安装的扩展是启用的，除非有明确禁用它们的配置。可以使用命令行禁用或启用扩展。扩展或扩展中的单个插件可以被另一个扩展禁用。

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

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

使用命令行时，您可以指定配置的 --level：user、system 或 sys-prefix（默认）。

一个示例 <jupyter_config_path>/labconfig/page_config.json 可能如下所示：

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

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

使用 `jupyter labextension` 安装/卸载 #

注意

强烈不建议使用这种方式安装/卸载 JupyterLab 扩展。

jupyter labextension 命令使您能够从 npm 安装或卸载源扩展。请参阅 jupyter labextension --help 以获取帮助。但要安装这些源扩展，您首先需要安装 Node.js。

安装 Node.js#

源扩展需要 Node.js 来重建 JupyterLab 并激活扩展。如果您使用 conda 和 conda-forge 包，您可以使用以下命令获取 Node.js

conda install -c conda-forge nodejs

如果您使用带有默认 Anaconda 包的 conda（即，您通常不使用 conda-forge），则应改用 conda install nodejs 从 Anaconda 默认通道安装 Node.js。

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

安装和卸载源扩展#

您可以使用以下命令从 npm 安装源扩展

jupyter labextension install my-extension my-other-extension

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

jupyter labextension install my-extension@1.2.3

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

注意

安装源扩展将需要安装 Node.js 并需要重新构建 JupyterLab。

使用以下命令卸载源扩展

jupyter labextension uninstall my-extension my-other-extension

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

jupyter lab build

注意

如果您在 Windows 上重建 JupyterLab，您可能会遇到 FileNotFoundError，这是由于 Windows 上的默认路径长度造成的。Node 模块存储在深度嵌套的目录结构中，因此路径可能会变得非常长。如果您拥有管理权限并且使用的是 Windows 10 或更高版本，您可以通过添加专用注册表键来启用长路径。

扩展#

安装扩展#

在 PyPI 上浏览扩展#

使用扩展管理器管理扩展#

免责声明#

查找扩展#

安装扩展#

管理已安装的扩展#

配置扩展管理器#

PyPI 管理器设置#

列表#

默认模式#

黑名单模式#

白名单模式#

列表配置#

使用插件管理器管理插件#

锁定和解锁插件#

使用 jupyter labextension 管理扩展#

列出已安装的扩展#

启用和禁用扩展#

使用 jupyter labextension 安装/卸载#

安装 Node.js#

安装和卸载源扩展#

此页面

安装扩展 #

使用扩展管理器管理扩展 #

使用插件管理器管理插件 #

使用 `jupyter labextension` 管理扩展 #

使用 `jupyter labextension` 安装/卸载 #