扩展

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

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

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

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

在PyPI上浏览扩展

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

• Framework :: Jupyter :: JupyterLab

• 框架 :: Jupyter :: JupyterLab :: 1

• Framework :: Jupyter :: JupyterLab :: 2

• Framework :: Jupyter :: JupyterLab :: 3

• Framework :: Jupyter :: JupyterLab :: 4

• 框架 :: Jupyter :: JupyterLab :: 扩展

• Framework :: Jupyter :: JupyterLab :: 扩展 :: Mime 渲染器

• Framework :: Jupyter :: JupyterLab :: 扩展 :: 预构建

• 框架 :: Jupyter :: JupyterLab :: 扩展 :: 主题

注意

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

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

• 对你来说很容易，通常可以直接通过项目的源代码网站，例如GitHub或GitLab，

• 便于维护者审查和合并，以及

• 可以对软件包的发现性产生积极影响

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

注意

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

如果Python包具有以下分类器，则扩展将被列出： Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt 此外，建议扩展作者提供install.json文件 以指定确切的Python包名称。

警告

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

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

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

免责声明

危险

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

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

图：用户未确认免责声明

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

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

图： 免责声明已勾选

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

查找扩展

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

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

安装扩展

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

危险

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

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

管理已安装的扩展

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

配置扩展管理器

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

• pypi: [默认] 允许从 PyPI.org 安装/卸载扩展

• readonly: 显示已安装的扩展（具有禁用/启用它们的能力）

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

jupyter lab --LabApp.extension_manager=readonly

PyPI 管理器设置

pypi 管理器有特定的选项，可以使用命令行选项进行设置：

• --PyPIExtensionManager.base_url: PyPI仓库基础URL - 默认为 https://pypi.org/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 将使用黑名单并从您的搜索结果中移除所有被列入黑名单的 扩展。

如果您在扩展程序被列入黑名单之前已经安装了它，已安装列表中的扩展程序条目将以红色高亮显示。建议您卸载它。您可以将鼠标悬停在问号图标上以阅读说明。

图： 应移除的已安装扩展黑名单

白名单模式

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

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

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

图： 已安装的第二个扩展已从允许列表中移除，应予以删除

列表配置

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

• 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命令。

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

锁定和解锁插件

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

jupyter labextension lock my-extension:plugin

要解锁一个被锁定的插件：

jupyter labextension unlock my-extension:plugin

锁定的插件在插件列表中显示为带有锁定图标，并且无法从用户界面启用/禁用：

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

列出已安装的扩展

列出所有已安装的扩展：

jupyter labextension list

注意

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

启用和禁用扩展

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

jupyter labextension disable my-extension

您可以通过以下方式启用已禁用的扩展：

jupyter labextension enable my-extension

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

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

• 存在/labconfig/page_config.json文件，其中包含一个disabledExtensions键，该键是一个以包名作为键和布尔值作为值的对象。

• (已弃用) 在 /settings/page_config.json 中存在 disabledExtensions 键。 此值是禁用扩展的列表，但已弃用，推荐使用 labconfig 位置的分层配置方法。

• 在另一个JupyterLab扩展的元数据中存在disabledExtensions键，该键会禁用给定的扩展。如果该扩展本身被禁用，则该键将被忽略。

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

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

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

请参阅LabConfig目录的文档以获取更多信息。

注意

这种安装/卸载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

如果您使用conda与默认的Anaconda包（即您通常不使用conda-forge），您应该从Anaconda默认频道安装Node.js，使用conda install nodejs来代替。

您也可以从系统包管理器中获取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压缩包，或者一个指向gzipped压缩包的URL。

注意

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

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

jupyter labextension uninstall my-extension my-other-extension

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

jupyter lab build

注意

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