筆記本層級的 Python 程式庫

筆記本範圍的連結庫可讓您建立、修改、儲存、重複使用及共用筆記本專屬的自定義 Python 環境。 當您安裝筆記本範圍的程式庫時，只有目前的筆記本及與該筆記本相關聯的任何作業可存取該程式庫。 連結至相同叢集的其他筆記本不會受到影響。

Notebook 範圍內的程式庫不會在不同工作階段之間保留。 您必須在每個工作階段開始時重新安裝筆記本範圍的程式庫，或在筆記本中斷與叢集的連結時重新安裝。

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 說明文件及相關頁面。

重要

  • %pip 指令不會自動重新啟動 Python 程序。 如果您安裝新的套件或更新現有的套件，您可能需要使用 dbutils.library.restartPython() 來查看新的套件。 請參閱在 Azure Databricks 上重新啟動 Python 程序。
  • 使用 %pip 升級、修改或解除安裝核心 Python 套件（例如 IPython）可能會導致某些功能無法如預期運作。 如果您遇到這類問題，請重新啟動叢集或啟動新的工作階段來重設環境。

更快的安裝方式 %uv pip

注意

%uv pip 僅在運行環境 版本 5 或以上的無伺服器筆記本上提供。 經典運算及早期的無伺服器環境版本不支援 %uv pip。

%uv pip 魔法指令是比 %pip 更快的替代方案。 %uv pip 由 UV 套件管理器驅動，並與 共享相同的筆記本虛擬環境 %pip，因此用一個工具安裝的套件會被另一個工具看到。

%uv pip 比 %pip 安裝和唯讀操作（如 list）更快。 這使得它非常適合在環境規範之上進行迭代。

%uv pip支援標準pip子指令：install、、uninstalllist、 showfreezechecktree和 。

%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 解除安裝程式庫

注意

您無法解除安裝包含在 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 支援，以及使用其他版本控制系統的範例。

使用 Databricks 秘密所管理的認證來安裝私人套件 %pip

pip 支援使用 基本身份驗證從私人來源安裝套件，包括私人版本控制系統和私人套件存放庫，例如 Nexus 和 Artifactory。 秘密管理可透過 Databricks 秘密 API 取得，可讓您儲存驗證令牌和密碼。 使用 DBUtils API 在您的筆記本中存取機密。 請注意，您可以在 magic 命令中使用 $variables 。

若要從私有存放庫安裝套件，請在 %pip install 中指定 --index-url 選項來提供存放庫 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 目錄磁碟區上。

您可以使用 %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 的功能。 啟用 automagic 時，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 上，Notebook 範圍的程式庫與批次串流工作不相容。 Databricks 建議改用 叢集連結庫 或 IPython 核心 。
  • Last updated on