限定于笔记本的 Python 库

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

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

Databricks 建议使用 %pip 魔法命令来安装限于笔记本的 Python 库。 在运行 环境版本 5 或更高版本的无服务器笔记本上，您还可以使用 %uv pip 以加快安装速度。

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

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

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

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

使用 %pip 命令管理库

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

借助 %uv pip 实现更快的安装

%uv pip 魔术命令是 %pip 的更快替代方案。 %uv pip 使用 uv 包管理器，并与 %pip 共享同一个笔记本虚拟环境，因此使用其中一个工具安装的软件包对另一个工具也可见。

%uv pip 比 %pip 安装和只读操作（例如 list）更快。 这使得它非常适合在环境规范的基础上进行迭代。

%uv pip支持标准pip子命令：install、、uninstall、listshow、freeze、、 check和tree。

%uv pip install simplejson

%uv pip list

此页上的其他安装模式（卷、工作区文件、要求文件、版本控制、专用存储库）适用于 %uv pip。 可以在其中任一示例中替换%pip%uv pip。

%uv pip 限制

• %uv pip uninstall 无法完全删除预安装在无服务器环境中的库。 仅删除包元数据。 基础文件保留在文件系统上，包仍可导入。
• %uv pip 不检查针对预安装的库的依赖项冲突。
• 运行 %uv pip 命令后， 笔记本的环境端 面板可能会在用户安装时显示一些预安装的库。 这是一个显示问题，不会影响包功能。
• %uv pip 适用于快速交互式迭代。 若要为笔记本设置可重现的环境，请在笔记本 的环境侧面板中 添加依赖项。

使用 %pip 来安装库

%pip install matplotlib

使用 %pip 安装 Python wheel 包

%pip install /path/to/my_package.whl

使用 %pip 卸载库

%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 选项将存储库 URL 指定给 %pip install，或将其添加到位于 pip 的 ~/.pip/pip.conf 配置文件中。

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 安装包

可以使用 %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_D8ds_v5。
• 对于 10 节点 GPU 群集，请使用 Standard_NC12。

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

%pip、%sh pip 和 !pip 之间的区别

%sh 和 ! 在笔记本中执行 shell 命令；前者是 Databricks 辅助 magic 命令，而后者是 IPython 的一项功能。 pip 是当启用了 %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 内核。