通过

笔记本范围内的 Python 库

  • 项目

笔记本范围内的库允许你创建、修改、保存、重用和共享特定于笔记本的自定义 Python 环境。 安装笔记本范围内的库时，只有当前笔记本以及与该笔记本关联的任何作业有权访问该库。 附加到同一群集的其他笔记本不受影响。

笔记本范围内的库不会跨会话保留。 必须在每个会话开始时或从群集中分离笔记本时，重新安装笔记本范围内的库。

Databricks 建议使用 %pip magic 命令安装笔记本范围的 Python 库。

可以在计划为作业的笔记本中使用 %pip。 如果需要在 Scala、SQL 或 R 笔记本中管理 Python 环境，请将 %python magic 命令与 %pip 结合使用。

使用笔记本范围的库安装时，可能会有比较多的流量进入驱动程序节点。 请参阅使用笔记本范围的库时驱动程序节点应有多大？。

若要为附加到群集的所有笔记本安装库，请使用群集库。 请参阅群集库。

有关可用于在 Databricks 中安装 Python 库的选项的综合概述，请参阅 Python 环境管理。

注意

在 Databricks Runtime 10.4 LTS 及更低版本上，可以使用 (旧版) Azure Databricks 库实用工具。 库实用工具仅在 Databricks Runtime 上受支持，而在 Databricks Runtime ML 不受支持。 请参阅库实用工具 (dbutils.library)（旧版）。

使用 %pip 命令管理库

%pip 命令等效于 %pip 命令并支持相同的 API。 以下部分介绍如何使用 %pip 命令来管理环境的示例。 有关使用 pip 安装 Python 包的详细信息，请参阅 pip和相关页面。

重要

  • 从 Databricks Runtime 13.0 开始，%pip 命令不会自动重启 Python 进程。 如果安装新包或更新现有包，可能需要使用 dbutils.library.restartPython() 来查看新包。 请参阅在 Azure Databricks 上重启 Python 进程。
  • 在 Databricks Runtime 12.2 LTS 及更低版本上，Databricks 建议将所有 %pip 命令放在笔记本的开头。 在修改环境的任何 %pip 命令后，会重置笔记本状态。 如果在笔记本中创建 Python 方法或变量，然后在后面的一个单元格中使用 %pip 命令，则这些方法或变量会丢失。
  • 使用 %pip 升级、修改或卸载核心 Python 包（如 IPython），可能会导致某些功能无法按预期正常工作。 如果遇到此类问题，可以通过拆离并重新附加笔记本或者通过重启群集来重置环境。

使用 %pip 安装库

%pip install matplotlib

使用 %pip 安装 Python wheel 包

%pip install /path/to/my_package.whl

使用 %pip 卸载库

注意

你无法卸载 Databricks Runtime 发行说明版本和兼容性中包含的库，或作为群集库安装的库。 如果你安装的库版本不同于 Databricks Runtime 中包含的版本或在群集上安装的版本，则可以使用 %pip uninstall 将库还原为 Databricks Runtime 中的默认版本或在群集上安装的版本，但不能使用 %pip 命令卸载 Databricks Runtime 中包含的库版本或在群集上安装的库版本。

%pip uninstall -y matplotlib

需要 -y 选项。

使用 %pip 从版本控制系统安装库

%pip install git+https://github.com/databricks/databricks-cli

可以向 URL 添加参数，以指定版本或 Git 子目录等。 有关详细信息以及使用其他版本控制系统的示例，请参阅 VCS 支持。

使用 %pip 通过 Databricks 机密管理的凭据安装专用包

Pip 支持通过基本身份验证从专用源安装包，包括专用版本控制系统和专用包存储库，如 Nexus 和 Artifactory。 机密管理可通过 Databricks 机密 API 获得，因此可以存储身份验证令牌和密码。 使用 DBUtils API 从笔记本访问机密。 请注意，可以在 magic 命令中使用 $variables。

若要从专用存储库安装包，请使用 --index-url 选项指定链接到 %pip install 的存储库 URL，或将其添加到 ~/.pip/pip.conf 中的 pip 配置文件。

token = dbutils.secrets.get(scope="scope", key="key")

%pip install --index-url https://<user>:$token@<your-package-repository>.com/<path/to/repo> <package>==<version> --extra-index-url https://pypi.org/simple/

同样，可以将机密管理与 magic 命令结合使用，从版本控制系统安装专用包。

token = dbutils.secrets.get(scope="scope", key="key")

%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

使用 %pip 从 DBFS 安装包

重要

任何工作区用户都可以修改存储在 DBFS 中的文件。 Azure Databricks 建议将文件存储在工作区或 Unity Catalog 卷上。

可以使用 %pip 安装已保存在 DBFS 上的专用包。

将文件上传到 DBFS 时，它将自动重命名该文件，并使用下划线替换空格、句点和连字符。 对于 Python wheel 文件，pip 要求文件名在版本中使用句点（例如 0.1.0）和连字符，而不能使用空格或下划线，因此这些文件名不会更改。

%pip install /dbfs/mypackage-0.0.1-py3-none-any.whl

使用 %pip 从卷安装包

重要

此功能目前以公共预览版提供。

借助 Databricks Runtime 13.3 LTS 及更高版本，可以使用 %pip 安装已保存到卷的专用包。

将文件上传到卷时，它将自动重命名该文件，并使用下划线替换空格、句点和连字符。 对于 Python wheel 文件，pip 要求文件名在版本中使用句点（例如 0.1.0）和连字符，而不能使用空格或下划线，因此这些文件名不会更改。

%pip install /Volumes/<catalog>/<schema>/<path-to-library>/mypackage-0.0.1-py3-none-any.whl

使用 %pip 安装存储为工作区文件的包

通过 Databricks Runtime 11.3 LTS 及更高版本，可以使用 %pip 安装已保存为工作区文件的专用包。

%pip install /Workspace/<path-to-whl-file>/mypackage-0.0.1-py3-none-any.whl

在要求文件中保存库

%pip freeze > /Workspace/shared/prod_requirements.txt

文件路径中的任何子目录都必须已存在。 运行 %pip freeze > /Workspace/<new-directory>/requirements.txt 时，如果目录 /Workspace/<new-directory> 尚不存在，则该命令会失败。

使用要求文件安装库

要求文件包含要使用 pip 安装的包的列表。 以下是使用要求文件的示例：

%pip install -r /Workspace/shared/prod_requirements.txt

有关 requirements.txt 文件的详细信息，请参阅要求文件格式。

使用笔记本范围的库时驱动程序节点应有多大？

使用笔记本范围内的库可能会导致更多的流量流向驱动程序节点，因为它可使环境在执行程序节点之间保持一致。

当使用包含 10 个或更多个节点的群集时，Databricks 建议驱动程序节点至少满足以下规范：

  • 对于 100 节点 CPU 群集，请使用 Standard_DS5_v2。
  • 对于 10 节点 GPU 群集，请使用 Standard_NC12。

对于更大的群集，请使用更大的驱动程序节点。

能否使用 %sh pip、!pip 或 pip？ 有何不同？

%sh 和 ! 在笔记本中执行 shell 命令；前者是 Databricks 辅助 magic 命令，而后者是 IPython 的一项功能。 pip 是启用 automagic 时 %pip 的简写，这是 Azure Databricks Python 笔记本中的默认设置。

在 Databricks Runtime 11.3 LTS 及更高版本上，%pip、%sh pip 和 !pip 都将库安装为笔记本范围的 Python 库。 在 Databricks Runtime 10.4 LTS 及更低版本中，Databricks 建议仅使用 %pip 或 pip 来安装笔记本范围的库。 %sh pip 和 !pip 的行为在 Databricks Runtime 10.4 LTS 及更低版本中不一致。

已知问题

  • 在 Databricks Runtime 9.1 LTS 上，笔记本范围的库与批量流式处理作业不兼容。 Databricks 建议改用群集库或 IPython 内核。