Azure Databricksの「Databricks Utilities（dbutils）reference」が更新され、「設定変更や移行が必要なのか」「料金が変わるのか」と気になっている方も多いでしょう。
結論として、今回の情報は、dbutilsの課金開始やワークスペース全体の強制設定変更を伴う新機能リリースではありません。現行仕様、利用条件、非推奨機能を整理したリファレンス更新として確認するのが適切です。
ただし、DBFS rootやDBFSマウント、旧dbutils-api、一部のdbutils.libraryを使っている環境は注意が必要です。すぐに停止する期限は示されていませんが、Unity Catalogボリュームや現行SDKへの移行準備を始めるべき段階に入っています。(Microsoft Learn)
Azure DatabricksのDatabricks Utilities（dbutils）referenceで確認すべき変更点
2026年6月16日付の更新情報として扱われた項目ですが、参照先のMicrosoft Learnには「2026年6月10日最終更新」と表示されています。また、Azure Databricksの2026年6月リリースノートを確認しても、6月16日付でdbutils単独の機能リリースは見当たりません。
そのため、「6月16日にdbutilsの動作が一斉に変わった」と判断するのではなく、現在サポートされている使い方と、今後避けるべき使い方を確認する更新として捉えるのが安全です。(Microsoft Learn)
| 確認項目 | 現行の公式情報 | 必要な対応 |
|---|---|---|
| Azure側の強制設定変更 | 今回のリファレンスに記載なし | 原則不要 |
| dbutilsの利用条件 | DBFSを使用するコンピューティング環境が必要 | 利用中のコンピュートで実行確認 |
| DBFS root・マウント | 非推奨 | Unity Catalogボリュームなどへ移行を検討 |
dbutils.library | 大半のメソッドが非推奨 | %pipを中心とした管理へ変更 |
dbutils-api | 非推奨 | Databricks SDKなどへ移行 |
| 料金改定 | 今回の更新では示されていない | 実行時間とストレージ処理を監視 |
| 廃止期限 | dbutils全体の終了期限は記載なし | 社内期限を決めて段階的に移行 |
Databricks Utilities（dbutils）とは
Databricks Utilitiesは、Azure Databricksのノートブックからファイル、ジョブ、シークレット、ウィジェットなどを操作するためのユーティリティです。Python、R、Scalaのノートブックで利用できます。
主なモジュールは次のとおりです。
| モジュール | 主な用途 |
|---|---|
dbutils.fs | ファイルやディレクトリのコピー、移動、削除、一覧取得 |
dbutils.jobs | ジョブのタスク間で値を受け渡す |
dbutils.notebook | 別ノートブックの実行、終了値の受け渡し |
dbutils.secrets | シークレットスコープから認証情報を取得 |
dbutils.widgets | ノートブックの入力パラメーターを作成・取得 |
dbutils.data | DataFrameの統計情報を要約 |
dbutils.library | ライブラリ管理。一部を除いて非推奨 |
利用可能なモジュールやコマンドは、Databricks Runtimeや言語によって異なる場合があります。実際の環境では、次のコマンドで確認するのが確実です。(Microsoft Learn)
dbutils.help()
dbutils.fs.help()
dbutils.widgets.help()
dbutils.jobs.help()特定のコマンドだけを確認する場合は、次のように実行します。
dbutils.fs.help("cp")
dbutils.widgets.help("getAll")「DBFS対応が必要」と「DBFS root・マウント非推奨」は矛盾しない
公式リファレンスには、dbutilsはDBFSを使用するコンピューティング環境だけをサポートすると記載されています。一方、別の公式ドキュメントでは、DBFS rootとDBFSマウントが非推奨とされています。
ここで区別すべきなのは、次の2点です。
- DBFSというファイルアクセスの仕組み
dbfs:/FileStoreなどのDBFS rootや、/mnt配下のDBFSマウント
非推奨の対象は、主に後者のDBFS rootとDBFSマウントです。dbutils.fsそのものが廃止されるわけではありません。新しい構成では、Unity Catalogボリュームの/Volumes/<catalog>/<schema>/<volume>/や、Unity Catalogの外部ロケーションを利用します。(Microsoft Learn)
例えば、次のような従来パスを使っている場合は移行候補です。
dbutils.fs.ls("/mnt/raw-data/")
dbutils.fs.ls("dbfs:/FileStore/import/")移行後は、事前にカタログ、スキーマ、ボリューム、権限を設定したうえで、次のようなパスを利用します。
dbutils.fs.ls("/Volumes/main/landing/raw-data/")パス文字列だけを置き換えても動作しません。Unity Catalog側でボリュームを作成し、実行ユーザーやサービスプリンシパルに必要な権限を付与する必要があります。
今回の更新で影響を受ける人
ノートブックやジョブの開発者
次のコードを使っている場合は影響を確認してください。
dbutils.fs.mount()やdbutils.fs.updateMount()dbutils.libraryによるライブラリのインストールdbutils.widgets.getArgument()dbutils.notebook.run()による複雑なノートブック連携- SparkのUDFや
map処理内からのdbutils呼び出し
特に、dbutils.widgets.getArgument()は非推奨です。原則としてdbutils.widgets.get()へ置き換えます。(Microsoft Learn)
# 旧方式
value = dbutils.widgets.getArgument("target_date", "")
# 推奨方式
value = dbutils.widgets.get("target_date")Azure Databricksの管理者
管理者は、コードだけでなく次の構成も確認する必要があります。
- DBFS rootに本番データやライブラリを保存していないか
- DBFSマウントでAzure Storageへ接続していないか
- シークレットスコープの読み取り権限が広すぎないか
- 新しいワークスペースでも従来のDBFSパスを前提にしていないか
- Databricks Runtime更新時の回帰テストが用意されているか
新しいアカウントでは、DBFS rootやDBFSマウントにアクセスできない構成が採用される場合があります。既存環境で動作していることだけを理由に、新規環境でも利用できると判断しないことが重要です。(Microsoft Learn)
Databricks Connectやローカル開発を利用する開発者
ノートブック内の組み込みdbutilsと、ローカル環境からSDK経由で利用するdbutilsは、使用できる機能が同一ではありません。
旧dbutils-apiライブラリは非推奨です。ローカル開発やCI/CDでは、Databricks SDK for PythonのWorkspaceClientなど、現在推奨されているSDKへの移行を検討します。(Microsoft Learn)
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()
files = workspace.dbutils.fs.ls("/")ローカル環境からUnity Catalogボリュームを操作する場合は、dbutilsではなくSDKのFiles APIを使う構成も確認してください。
Azure Databricksを直接利用しない一般ユーザー
SQLレポートやBIツールだけを利用し、背後のノートブックやジョブを管理していないユーザーへの直接的な影響は限定的です。
ただし、レポートのデータ更新処理が非推奨のDBFSマウントやdbutilsコードに依存している場合、将来的に更新ジョブが失敗する可能性があります。担当チームに依存関係を確認しておくと安心です。
設定・更新・移行で確認すべきこと
新しい設定を有効にする必要はない
今回のリファレンス更新には、Azureポータルやワークスペース設定で必須となる新しいスイッチは記載されていません。
まずは対象ノートブックを実際のコンピュートに接続し、次のコマンドが利用できるかを確認します。
dbutils.help()その後、利用中のモジュールごとに.help()を実行してください。ドキュメントだけで判断するより、利用中のDatabricks Runtimeで確認する方が確実です。
dbutilsを個別にアップデートする必要はない
ノートブック内の組み込みdbutilsは、通常、Databricks Runtime側から提供されます。一般的なPythonパッケージのように、利用者がdbutils本体をpip installして更新するものではありません。
一方、Databricks SDKやローカル開発用ライブラリは依存関係として管理します。SDKを更新する場合は、検証環境で動作確認してから本番へ反映してください。
Pythonでdbutils.fsを利用するときは、キーワード引数がsnake_caseになる点にも注意が必要です。ヘルプにextraConfigsと表示されても、Pythonではextra_configsを指定します。(Microsoft Learn)
非推奨機能は次の順番で移行する
| 現在の実装 | 推奨する移行先 |
|---|---|
dbfs:/FileStoreなどのDBFS root | Unity Catalogボリューム、ワークスペースファイル |
/mntとdbutils.fs.mount() | Unity Catalog外部ロケーション、外部ボリューム |
dbutils.library.install()など | %pipによるノートブックスコープ管理 |
dbutils.widgets.getArgument() | dbutils.widgets.get() |
dbutils-api | Databricks SDKまたは言語別の現行ライブラリ |
| Executor内でのdbutils呼び出し | Spark標準API、ドライバー側の前処理 |
dbutils.libraryでは大半のメソッドが非推奨ですが、Pythonプロセスを再起動するdbutils.library.restartPython()は、パッケージ更新後の再読み込みに引き続き使われます。(Microsoft Learn)
%pip install --upgrade databricks-sdk
dbutils.library.restartPython()料金への影響
今回の公式リファレンスには、dbutils固有の課金開始や価格改定は記載されていません。dbutilsのコマンドを呼び出した回数に対して、独立した利用料金が設定されたという情報でもありません。
ただし、コマンドが実行する処理には通常のコンピュート、ストレージ、ネットワーク利用が伴います。Azure Databricksの利用料金は、選択したコンピュートや実行時間などによって変わります。(Microsoft Azure)
特に注意したいのがdbutils.data.summarize()です。このコマンドはDataFrame全体を解析するため、大規模なDataFrameに対して実行すると処理時間とコンピュート消費が増える可能性があります。(Microsoft Learn)
コストを抑えるには、次のように対象データを絞ってから実行します。
sample_df = df.limit(100000)
dbutils.data.summarize(sample_df)本番データ全体に対して安易に実行せず、サンプリングや列の選択を先に行うのが安全です。
移行期限は設定されているか
今回のdbutilsリファレンスには、dbutils全体の廃止日や、dbutils-api、DBFS root、DBFSマウントを一律に停止する日付は記載されていません。
ただし、「期限がない」ことと「対応を先送りしてよい」ことは別です。新しいアカウントではDBFS rootやマウントが利用できない場合があり、古い構成のままではワークスペース追加や環境再構築時に問題が表面化します。(Microsoft Learn)
公式期限を待つのではなく、社内では次のような期限を設定すると進めやすくなります。
| 時期 | 実施内容 |
|---|---|
| 1週間以内 | 非推奨APIとDBFSパスを検索 |
| 次回の保守作業まで | getArgumentや旧ライブラリ管理を置換 |
| 次回のRuntime更新前 | ジョブ、ウィジェット、シークレット処理を回帰テスト |
| 新規開発時 | DBFS rootとマウントの新規採用を禁止 |
| 中期対応 | Unity Catalogボリュームへデータと権限を移行 |
5分でできる影響確認手順
ノートブック内で利用可能な機能を確認する
dbutils.help()
dbutils.fs.help()
dbutils.library.help()
dbutils.widgets.help()
dbutils.jobs.help()Gitリポジトリやエクスポート済みコードを検索する
ripgrepを利用できる場合は、次のように検索できます。
rg -n 'dbfs:/|/mnt/|dbutils\.fs\.(mount|mounts|updateMount|unmount)' .
rg -n 'dbutils-api|dbutils\.library\.|dbutils\.widgets\.getArgument' .Visual Studio Codeなどを使っている場合も、同じ文字列をワークスペース全体で検索してください。
検出結果を優先度で分類する
優先度が高いもの
- 本番データをDBFS rootに保存している
- 多数のジョブが同じDBFSマウントに依存している
- シークレットやストレージ資格情報をコードに直接記述している
- Executor内でdbutilsを呼び出している
- 新旧ワークスペース間で同じコードを共用する予定がある
優先度が比較的低いもの
dbutils.fs.ls()でUnity Catalogボリュームを参照しているdbutils.secrets.get()を適切な権限管理のもとで利用している%pip後のdbutils.library.restartPython()だけを使っている
運用で失敗しやすいポイント
DBFSマウントを稼働中に変更する
ジョブが読み書きしている最中にマウントを変更すると、処理失敗や参照先の不一致につながります。既存マウントを更新する場合はジョブを停止し、変更後に他の稼働中クラスターでもdbutils.fs.refreshMounts()を実行します。(Microsoft Learn)
シークレットのマスクを完全なアクセス防止だと考える
ノートブック上ではシークレット値がマスクされる場合がありますが、管理者、作成者、読み取り権限を持つユーザーによる参照を完全に防ぐ仕組みではありません。シークレットスコープのACLを最小権限にしてください。(Microsoft Learn)
taskValuesを通常実行のノートブックでテストする
dbutils.jobs.taskValuesはPython向けで、ジョブ実行中のタスク間連携を目的としています。ジョブ外でget()を呼ぶと、debugValueを指定しない限りエラーになります。1回のジョブ実行で設定できるタスク値は最大250個で、値のJSON表現にもサイズ制限があります。(Microsoft Learn)
dbutils.notebook.run()で大量データを返す
dbutils.notebook.run()の戻り値は文字列で、最大サイズは5MBです。大量データを返す用途には向きません。データ本体はテーブルやUnity Catalogボリュームへ保存し、戻り値ではパス、件数、処理IDなど小さな情報だけを渡します。(Microsoft Learn)
Executorからdbutilsを呼び出す
SparkのExecutor内でdbutilsを呼び出すと、予期しない結果やエラーになる可能性があります。ファイル一覧の取得やシークレットの読み込みはドライバー側で済ませ、必要な情報だけをSpark処理へ渡してください。(Microsoft Learn)
まず非推奨コードの有無を確認する
今回のDatabricks Utilities（dbutils）referenceの更新で、すべての利用者が直ちにAzureの設定や料金プランを変更する必要はありません。
最初に行うべきことは、ノートブックとジョブから次の利用箇所を検索することです。
dbfs:/や/mnt/dbutils.fs.mount()dbutils.libraryの旧メソッドdbutils.widgets.getArgument()dbutils-api- Executor内のdbutils呼び出し
該当箇所がなければ、今回の直接的な対応は限定的です。該当する場合は、DBFS rootやマウントを最優先とし、Unity Catalogボリューム、外部ロケーション、現行SDKへ段階的に移行してください。
コメント