高级用法#

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

  • 应用程序目录: JupyterLab 存储 JupyterLab 主要构建及其相关数据的地方，包括内置到 JupyterLab 的扩展。

  • 用户设置目录: JupyterLab 存储用户级别的 JupyterLab 扩展设置的地方

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

JupyterLab 还支持从 Jupyter 路径层次结构中的 Jupyter config 目录的 labconfig 子目录中获取配置数据的 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版本，默认的工作组合的npm包存储在JupyterLab附带的yarn.lock文件中。

禁用重建检查#

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

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

实验室配置目录#

对于jupyter --paths中列出的每个配置路径，/labconfig目录包含配置数据。来自所有这些目录的配置数据被合并成一个单一的配置，优先级由jupyter --paths给出。

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

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

  1. terminalsAvailable 标识是否可以通过启动器启动终端（即在Mac/Linux上的bash/tsch或在Windows上的PowerShell）。（此配置主要在Jupyter Lab中启用PowerShell访问之前的Windows上需要。）此字段的值为布尔值：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.*$"），则该特定插件将被禁用（或延迟）。

一个示例 /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的文件、已安装的扩展 和链接的包等。

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

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

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

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

扩展#

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

模式#

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

设置#

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应用程序目录是/local/share/jupyter/lab，则在/local/share/jupyter/lab/settings/overrides.json处创建此文件）。

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

JupyterLab 还允许您通过界面直接导出和导入一个overrides.json文件。您可以通过点击设置编辑器中的导出按钮，基于您当前的定制设置生成一个overrides.json文件。同样，您可以使用导入按钮来应用现有的overrides.json文件。这使得备份、共享或重用您的配置变得更加容易。

build_config.json#

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

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

暂存和静态#

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

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

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

主题#

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

JupyterLab 用户设置目录#

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

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

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

JupyterLab 工作区目录#

JupyterLab 会话始终位于一个工作区中。工作区包含 JupyterLab 的状态：当前打开的文件、应用程序区域和标签的布局等。当页面刷新时，工作区将被恢复。

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

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