高级用法#

JupyterLab 管理着几个不同的数据位置。这些位置可以通过运行 jupyter lab path 来查看。

  • 应用程序目录：JupyterLab 存储 JupyterLab 主要构建和相关数据的位置，包括内置于 JupyterLab 的扩展。

  • 用户设置目录：JupyterLab 存储 JupyterLab 扩展的用户级设置的位置。

  • 工作区目录：JupyterLab 存储工作区的位置。

JupyterLab 还遵循 LabConfig 目录，用于从 Jupyter 路径层次结构中 config 目录的 labconfig 子目录获取配置数据。

此外，JupyterLab 可以从 Jupyter data 目录的 labextensions 子目录加载动态联合（预构建）扩展，即捆绑其依赖项的扩展。

通过运行 jupyter --path 查看这些 Jupyter 配置路径的位置。

JupyterLab 构建过程#

要重建应用程序目录，请运行 jupyter lab build。默认情况下，jupyter labextension install 命令会构建应用程序，因此通常不需要直接调用 build。

构建包括以下步骤：

  • 使用模板文件填充 staging/ 目录。

  • 处理任何本地安装的包。

  • 确保所有安装的资产可用。

  • 捆绑资产。

  • 将捆绑的资产复制到 static 目录。

请注意，构建将始终使用满足 JupyterLab 本身和任何已安装扩展的依赖项要求的最新 JavaScript 包。如果您希望使用与 Python 包一起提供的固定要求集运行 JupyterLab，您可以以 jupyter lab --core-mode 的方式启动。

构建过程使用特定版本的 yarn，以及与 JupyterLab 一起提供的 yarn.lock 文件中存储的 npm 包的默认工作组合。

禁用重建检查#

JupyterLab 会自动检查是否需要在启动时重建。在某些情况下，例如自动化测试，您可能希望完全禁用启动重建检查。这可以通过在 jupyter_server_config.json（或 .py 等效文件）中设置 buildCheck 和 buildAvailable 来实现，该文件位于 jupyter --paths 返回的任何 config 位置。

{
  "LabApp": {
    "tornado_settings": {
      "page_config_data": {
        "buildCheck": false,
        "buildAvailable": false,
      }
    }
  }
}

LabConfig 目录#

对于在 jupyter --paths 中列出的每个配置路径 <jupyter_config_path>，<jupyter_config_path>/labconfig 目录包含配置数据。来自所有这些目录的配置数据将合并成一个单一的配置，优先级顺序由 jupyter --paths 决定。

JupyterLab 主要使用的文件是 page_config.json。 page_config.json 数据用于向应用程序环境提供配置数据。

此文件中可能存在以下配置

  1. terminalsAvailable 用于标识是否可以通过启动器启动终端（例如，Mac/Linux 上的 bash/tsch 或 Windows 上的 PowerShell）。（此配置主要在 Windows 上需要，因为在 Jupyter Lab 中启用 PowerShell 访问之前。）此字段的值为布尔值：true 或 false。

  2. disabledExtensions 控制哪些扩展完全不加载。

  3. deferredExtensions 控制哪些扩展在需要时才加载，而不管它们是否将 autoStart 设置为 true。

disabledExtensions 和 deferredExtensions 字段的值是具有布尔值的**对象**。对 disabledExtensions 和 deferredExtensions 中的模式执行以下检查顺序。

  • 如果配置值和包名称之间存在完全相同的字符串匹配（例如，"@jupyterlab/apputils-extension"），则禁用（或延迟）整个包。

  • 如果字符串值被编译为正则表达式，并且对包名称进行正则表达式匹配（例如，"@jupyterlab/apputils*$"），则禁用（或延迟）整个包。

  • 如果配置值和包中单个插件 ID 之间存在完全相同的字符串匹配（例如，"@jupyterlab/apputils-extension:settings"），则禁用（或延迟）该特定插件。

  • 如果字符串值被编译为正则表达式，并且对包中单个插件 ID 进行正则表达式匹配（例如，"@jupyterlab/apputils-extension:set.*$"），则禁用（或延迟）该特定插件。

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

{
   "disabledExtensions": {
         "@jupyterlab/notebook-extension": true,
         "@jupyterlab/apputils-extension:settings": true
   },
   "deferredExtensions": {
          "@jupyterlab/apputils-extension:set.*$": true
   },
   "terminalsAvailable": false
}

有关更多信息，请参阅 有关启用和禁用扩展的文档。

JupyterLab 应用程序目录#

应用程序目录包含主要的 JupyterLab 应用程序文件，包括构建的资产、用于重建 JupyterLab 的文件、已安装的扩展和链接的包等。

默认情况下，应用程序目录位于 <sys-prefix>/share/jupyter/lab，其中 <sys-prefix> 是当前 Python 环境的特定于站点的目录前缀。可以通过运行 jupyter lab path 来查询当前应用程序路径。应用程序目录可以使用任何 JupyterLab 命令中的 --app-dir 命令行选项或通过设置 JUPYTERLAB_DIR 环境变量来覆盖。

我们建议用户不要在类 Unix 系统上的系统位置安装 JupyterLab，因为应用程序目录将是只读的。相反，请使用 conda 环境或 pip install --user jupyterlab，以便用户可以写入应用程序目录。

此目录位置和语义不遵循标准的 Jupyter 配置语义，因为我们需要构建一个统一的应用程序，而 Jupyter 的默认配置位置位于用户级别（用户的 home 目录）。通过显式使用 sys-prefix 目录，我们可以确保在虚拟环境中更好地隔离。

JupyterLab 应用程序目录包含子目录 extensions、schemas、settings、staging、static 和 themes。在本节的其余部分，我们将解释每个子目录。

extensions#

extensions 目录包含应用程序中每个已安装扩展的打包 tarball。如果应用程序目录与 sys-prefix 目录不同，则 sys-prefix 目录中安装的扩展将在应用程序目录中使用。如果应用程序目录中安装的扩展存在于 sys-prefix 目录中，它将覆盖 sys-prefix 版本。卸载扩展将首先卸载覆盖的扩展，然后在再次调用时尝试卸载 sys-prefix 版本。如果无法卸载 sys-prefix 版本，则可以使用 settings 中的 ignoredPackages 元数据忽略其插件。

schemas#

schemas 目录包含 JSON Schemas，这些 schemas 描述了各个扩展使用的设置。用户可以使用 JupyterLab 高级设置编辑器编辑这些设置。

settings#

JupyterLab 应用程序目录 内的 settings 目录可能包含 page_config.json、overrides.json 和/或 build_config.json 文件。

page_config.json（已弃用）#

此文件被认为已弃用。此文件可以包含与 LabConfig 目录中的 page_config.json 文件类似的数据，但 disabledExtensions 和 deferredExtensions 以字符串数组的形式给出。

page_config.json 文件的示例如下

{
    "disabledExtensions": [
        "@jupyterlab/toc"
    ],
    "terminalsAvailable": false
}

overrides.json#

可以通过在 overrides.json 文件中定义新的默认值来覆盖扩展设置的默认值。例如，如果您想将默认主题覆盖为深色主题，请在 应用程序设置目录 中创建一个包含以下行的 overrides.json 文件（例如，如果 JupyterLab 应用程序目录 为 <sys.prefix>/local/share/jupyter/lab，请在 <sys.prefix>/local/share/jupyter/lab/settings/overrides.json 中创建此文件）。

{
  "@jupyterlab/apputils-extension:themes": {
    "theme": "JupyterLab Dark"
  }
}

build_config.json#

build_config.json 文件用于跟踪使用 jupyter labextension install <directory> 安装的本地目录，以及已显式卸载的核心扩展。一个 build_config.json 文件的示例如下

{
    "uninstalled_core_extensions": [
        "@jupyterlab/markdownwidget-extension"
    ],
    "local_extensions": {
        "@jupyterlab/python-tests": "/path/to/my/extension"
    }
}

staging 和 static#

static 目录包含 JupyterLab 应用程序将加载的资产。 staging 目录用于创建构建，然后填充 static 目录。

运行 jupyter lab 将尝试运行应用程序目录中的 static 资产（如果存在）。您可以运行 jupyter lab --core-mode 从安装目录加载核心 JupyterLab 应用程序（即没有扩展的应用程序）。

如果 JupyterLab 启动且静态资产不存在，它将在控制台和浏览器中显示错误。

主题#

themes 目录包含 JupyterLab 主题扩展的资产（如 CSS 和图标）。

JupyterLab 用户设置目录#

用户设置目录包含 Jupyter 扩展的用户级设置。

默认情况下，位置为 $HOME/.jupyter/lab/user-settings/，其中 $HOME 是用户的 home 目录。此文件夹不在 JupyterLab 应用程序目录中，因为这些设置通常在 Python 环境之间共享。可以使用 JUPYTERLAB_SETTINGS_DIR 环境变量修改位置。

JSON5 文件会自动在此文件夹中创建，记录用户在 JupyterLab 高级设置编辑器中所做的设置更改。文件名遵循 <extension_name>/<plugin_name>.jupyterlab-settings 的模式。这些值会覆盖扩展提供的默认值，以及应用程序设置目录中 overrides.json 文件中的默认覆盖。

JupyterLab 工作区目录#

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

默认情况下，位置为 $HOME/.jupyter/lab/workspaces/，其中 $HOME 是用户的 home 目录。此文件夹不在 JupyterLab 应用程序目录中，因为这些文件通常在 Python 环境之间共享。可以使用 JUPYTERLAB_WORKSPACES_DIR 环境变量修改位置。

可以使用 工作区命令行工具 导入和导出这些文件以创建默认“配置文件”。

本页内容
在 GitHub 上编辑
显示源代码