Notebook スコープの Python ライブラリ

ノートブック スコープのライブラリを使用すると、ノートブックに固有のカスタム Python 環境を作成、変更、保存、再利用、共有できます。 ノートブック スコープのライブラリをインストールすると、現在のノートブックと、そのノートブックに関連付けられているすべてのジョブにのみ、そのライブラリへのアクセス権が付与されます。 同じクラスターにアタッチされている他のノートブックは影響を受けません。

ノートブック スコープのライブラリは、セッション間で保持されません。 各セッションの開始時、またはノートブックがクラスターからデタッチされるたびに、ノートブック スコープのライブラリを再インストールする必要があります。

Databricks では、%pip マジック コマンドを使用して、ノートブックスコープの Python ライブラリをインストールすることをお勧めします。

ジョブとしてスケジュールされたノートブックで %pip を使用できます。 Scala、SQL、または R ノートブックで Python 環境を管理する必要がある場合は、%python マジック コマンドを %pip と組み合わせて使用します。

ノートブック スコープのライブラリをインストールすると、ドライバー ノードへのトラフィックが増加する可能性があります。 「ノートブック スコープのライブラリを使用する場合、ドライバー ノードのサイズはどれくらいにする必要がありますか?」を参照してください。

クラスターにアタッチされているすべてのノートブックにライブラリをインストールするには、クラスター ライブラリを使用します。 「クラスター ライブラリ」を参照してください。

Note

Databricks Runtime 10.5 以下では、(レガシ) Azure Databricks ライブラリ ユーティリティを使用できます。 ライブラリ ユーティリティは Databricks Runtime でのみサポートされており、Databricks Runtime ML ではサポートされていません。 「ライブラリ ユーティリティ (dbutils.library) (レガシ)」を参照してください。

%pip コマンドを使用してライブラリを管理する

%pip コマンドは pip コマンドと同等であり、同じ API をサポートします。 以下のセクションでは、%pip コマンドを使用して環境を管理する方法の例を示します。 pip を使用した Python パッケージのインストールの詳細については、pip install のドキュメントと関連ページを参照してください。

重要

  • Databricks Runtime 13.0 以降、%pip コマンドでは Python プロセスは自動的に再起動されません。 新しいパッケージをインストールするか、既存のパッケージを更新する場合は、dbutils.python.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 を使用してライブラリをアンインストールする

Note

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 では、基本認証を使用してプライベート ソースからパッケージをインストールすることがサポートされています。このソースには、プライベートなバージョン管理システムや、NexusArtifactory などのプライベート パッケージ リポジトリが含まれます。 シークレット管理は、認証トークンとパスワードを保存するための Databricks Secrets API を介して利用できます。 DBUtils API を使用して、ノートブックからシークレットにアクセスします。 マジック コマンドで $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/

同様に、マジック コマンドでシークレット管理を使用して、バージョン管理システムからプライベート パッケージをインストールできます。

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 を使用して DBFS からパッケージをインストールする

重要

この機能はパブリック プレビュー段階にあります。

Databricks Runtime 13.2 以降では、 %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 > /dbfs/requirements.txt

ファイル パス内のすべてのサブディレクトリが既に存在している必要があります。 /dbfs/<new-directory> ディレクトリがまだ存在しない状態で %pip freeze > /dbfs/<new-directory>/requirements.txt を実行すると、コマンドは失敗します。

要件ファイルを使用してライブラリをインストールする

要件ファイルには、pip を使用してインストールするパッケージのリストが含まれます。 要件ファイルの使用例を次に示します。

%pip install -r /dbfs/requirements.txt

ファイルの詳細については、要件ファイルの形式requirements.txtに関するページを参照してください。

ノートブック スコープのライブラリを使用する場合、ドライバー ノードのサイズはどれくらいにする必要がありますか?

ノートブック スコープのライブラリを使用すると、Executor ノード間で環境の一貫性を保つ方向に作用するため、ドライバー ノードへのトラフィックが増加する可能性があります。

10 以上のノードがあるクラスターを使用する場合、Databricks では、ドライバー ノードの最小要件として次の仕様を推奨しています。

  • 100 ノード CPU クラスターの場合は、Standard_DS5_v2 を使用します。
  • 10 ノード GPU クラスターの場合は、Standard_NC12 を使用します。

より大規模なクラスターの場合は、より大規模なドライバー ノードを使用します。

%sh pip!pip、または pip を使用できますか? 違いは何ですか?

%sh! では、ノートブックでシェル コマンドが実行されます。前者は Databricks の補助マジック コマンドであり、後者は IPython の機能です。 pip は、automagic が有効になっている場合の %pip の短縮形です。これは、Azure Databricks Python ノートブックの既定です。

Databricks Runtime 11.0 以降では、%pip%sh pip!pip のすべてで、ノートブック スコープの Python ライブラリとしてライブラリがインストールされます。 Databricks Runtime 10.4 LTS 以降では、Databricks は、%pip または pip のみを使用してノートブック スコープ ライブラリをインストールすることをお勧めしています。 %sh pip!pip の動作は、Databricks Runtime 10.4 LTS 以下では一貫性がありません。

既知の問題

  • Databricks Runtime 10.3 以下では、ノートブック スコープのライブラリはバッチ ストリーミング ジョブと互換性がありません。 Databricks では、代わりにクラスター ライブラリまたは IPython カーネルを使用することをお勧めしています。