高级用法#

JupyterLab 管理其数据的多个不同位置。这些位置通过运行 jupyter lab path 显示

应用程序目录：JupyterLab 存储 JupyterLab 主构建及其关联数据（包括内置于 JupyterLab 的扩展）的位置。
用户设置目录：JupyterLab 存储 JupyterLab 扩展的用户级设置的位置。
工作区目录：JupyterLab 存储工作区的位置。

JupyterLab 还遵循 LabConfig 目录，用于从 Jupyter 路径层次结构中 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 --paths 返回的任何 config 位置的 jupyter_server_config.json（或等效的 .py 文件）中设置 buildCheck 和 buildAvailable 来实现。

{
  "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 数据用于向应用程序环境提供配置数据。

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

terminalsAvailable 标识是否可以通过启动器启动终端（即 Mac/Linux 上的 bash/tsch 或 Windows 上的 PowerShell）。 (此配置在 Jupyter Lab 中启用 PowerShell 访问之前主要针对 Windows 所需。)此字段的值为布尔值：true 或 false。
disabledExtensions 控制哪些扩展根本不应该加载。
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 的默认配置位置是在用户级别（用户主目录）。通过明确使用系统前缀目录，我们可以确保在虚拟环境中更好地隔离。

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

扩展#

extensions 目录包含应用程序中每个已安装扩展的打包 tarball。如果应用程序目录与 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 应用程序目录是 <sys.prefix>/local/share/jupyter/lab，则在 <sys.prefix>/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 <directory> 安装的本地目录，以及已明确卸载的核心扩展。一个 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 环境变量修改位置。

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

JupyterLab 工作区目录#

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

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

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