Databricks Gitフォルダサーバーレス (ベータ) を試す — 2つ目のノートブックでは環境設定をしなくていい

Posted at 2026-09-12

はじめに

2026年9月2日のリリースノートで、Git Folder Serverlessがベータとして登場しました。Gitフォルダ内のノートブックとファイルが、1つのサーバーレスコンピュートと、Gitフォルダのルートに置いた pyproject.toml で管理される1つの環境を共有する仕組みです。

サーバーレスノートブックを複数並べて開発していると、ノートブックを増やすたびに環境サイドパネルで同じライブラリを指定し直すことになります。この繰り返しがなくなるというのが、この機能の一番分かりやすい効果です。環境の持ち主がノートブックからGitフォルダに移る、と言い換えてもいいかもしれません。

実際にGitフォルダを1つ用意して、環境の共有まわりを中心に触っていきます。

環境の単位がノートブックからGitフォルダに移る

まず、従来のサーバーレスノートブックとの違いを整理しておきます。

	従来のサーバーレスノートブック	Git Folder Serverless
環境の指定場所	ノートブックごとの環境サイドパネル	Gitフォルダのルートの `pyproject.toml`
環境が効く範囲	そのノートブック1つ	同じGitフォルダのノートブックとファイル
コンピュート	ノートブックごと	Gitフォルダで1つを共有
依存関係の記録	ノートブックのメタデータ	`pyproject.toml` と `uv.lock` (Git管理下)

一番効いてくるのは最後の行だと思っています。依存関係がノートブックのメタデータではなくリポジトリのファイルになるので、環境がGitの履歴に乗ります。誰かがクローンしたときに同じ依存関係から始められる、という状態がプロジェクトのファイルとして表現されるわけです。

要件

ドキュメントに挙がっている要件は3つです。

プロジェクトがGitフォルダの中にあること
Gitフォルダをエディタで開くこと (Gitフォルダエディタ)
Gitフォルダのルートに pyproject.toml がすでにある場合、environment_version が5以降であること

3つ目が地味に引っかかりやすいところです。既存のリポジトリには pyproject.toml があっても、Databricks固有の記述は当然入っていません。今回も次のセクションを追記するところから始めました。

[tool.databricks.environment]
environment_version = "5"

サーバーレス環境バージョン5は2026年2月25日リリースでPythonは3.12.3です。バージョンごとの内容は環境バージョンにまとまっています。

Gitフォルダエディタでアタッチする

手順そのものは短いです。

サイドバーで「ワークスペース」をクリックし、対象のGitフォルダに移動する
「エディターで開く」をクリックする
Gitフォルダの中のノートブックまたはファイルを開く
コンピュートのドロップダウンメニューをクリックする
「Gitフォルダサーバーレス」を選択する
ノートブックまたはファイルを実行してコンピュートを起動する

ポイントは2の「エディターで開く」です。通常のノートブック画面からは選べず、Gitフォルダエディタで開いている必要があります。ノートブックを単体で開いたままコンピュートのドロップダウンを探しても見つからないので、ここで止まる人はいそうです。

同じGitフォルダの別のノートブックやファイルを開いて同じように「Gitフォルダサーバーレス」を選ぶと、そちらも同じコンピュートと環境にアタッチされます。

pyproject.tomlで環境を管理する

ここからが本題です。依存関係の追加には、ノートブックコマンドを使う方法と、pyproject.toml を直接編集する方法の2通りがあります。

どちらの場合も、Gitフォルダのルートに pyproject.toml がなければ先に作る必要があります。環境サイドパネルの「環境」セクションから作成できます。

ノートブックコマンドで追加する

Git Folder Serverlessにアタッチしたノートブックで、%uv add を実行するとルートの pyproject.toml に依存関係が追記されます。

%uv add cowsay

実行後の pyproject.toml はこうなりました。dependencies に行が増えています。

[project]
name = "data-engineering-w-databricks-free-edition"
version = "0.1.0"
dependencies = [
    "cowsay>=6.1",
]

[tool.databricks.environment]
environment_version = "5"

追記しただけでは共有環境には反映されません。%uv sync を実行すると、依存関係が共有環境に適用され、あわせて uv.lock が生成または更新されます。

%uv sync

%pip install のように「そのノートブックのセッションに入れる」操作ではなく、Gitフォルダの環境定義そのものを書き換える操作である、という点は意識しておいたほうがよさそうです。同じフォルダにアタッチしている他のノートブックにも影響します。

pyproject.tomlを直接編集する

エディタで pyproject.toml を開いて dependencies を直接書き換える方法もあります。バージョンを固定したいときはこちらのほうが早いです。

dependencies = [
    "cowsay>=6.1",
    "simplejson==3.18.1",
]

[tool.databricks.environment] の environment_version がDatabricks固有の指定です。値が文字列である点に注意してください。

編集しただけでは反映されません。ファイルエディタの上部にある「適用」をクリックすると、環境変更がGitフォルダサーバーレスに反映されます。ノートブックコマンドでいう %uv sync に相当する操作です。

反映後の環境は、環境サイドパネルから確認できます。「pyproject.tomlにより管理」と表示され、インストール済みの依存関係が一覧できます。

2つ目のノートブックでは何もしなくていい

まず、1つ目のノートブック「1. データ取り込み」で依存関係を追加し、共有環境に反映します。

%uv add cowsay
%uv sync

次に、同じGitフォルダの「2. データ変換とロード」を開き、コンピュートに「Gitフォルダサーバーレス」を選んでimportします。こちらでは %uv add も %uv sync も実行しません。

import cowsay

これが通ります。

大事なのは、2つ目のノートブックで何もしていないことです。%uv add も %uv sync も環境サイドパネルでの指定も不要で、コンピュートに「Gitフォルダサーバーレス」を選んで実行しただけです。ノートブックごとに環境を持っていたときは、同じライブラリをもう一度指定するところから始める必要がありました。フォルダに3つ4つとノートブックが並ぶほど、この差は効いてきます。

uv.lockがリポジトリに残る

%uv sync や「適用」で生成される uv.lock は、Gitフォルダの中のファイルなのでそのままコミット対象になります。

これが個人的には一番効く部分です。ノートブックの環境サイドパネルで指定した依存関係は、そのノートブックの外に出ていきません。pyproject.toml と uv.lock がリポジトリに入っていれば、環境の変更がプルリクエストのdiffに出てきます。「誰かがいつの間にかライブラリを1つ足していた」が、レビューできる変更になるということです。

共有されるもの、されないもの

コンピュートが共有されると聞くと、状態も共有されそうに思えますが、そうではありません。

同じGitフォルダのノートブックとファイルが、1つのGit Folder Serverlessコンピュートにアタッチする
アタッチできるのは、そのGitフォルダの中にあるアセットだけ
あるノートブックで定義したPython変数は、別のノートブックからは参照できない
アタッチしているノートブックやファイルから開いたWebターミナルは、同じコンピュート上で動く

3つ目が一番の勘所です。共有されるのはコンピュートリソースと環境であって、実行状態ではありません。ノートブック同士で値を受け渡したい場合は、これまでどおり %run やテーブル、ファイル経由といった手段が必要になります。

Webターミナルが同じコンピュート上で動くのは便利です。uv の状態やインストール済みパッケージをシェルから直接確認できるので、環境がおかしいときの切り分けがしやすくなります。

共同作業では各自がクローンする

Git Folder Serverlessのコンピュートを実行できるのは、それを起動したユーザーだけです。別のユーザーが同じGitフォルダを開いても、既存のコンピュート上でノートブックやファイルを実行することはブロックされます。

ドキュメントでは、コラボレーターがそれぞれ自分の個人ワークスペースフォルダにリポジトリをクローンし、各自がコンピュートと pyproject.toml 管理の環境を持つ形が推奨されています。変更のやり取りはブランチ、コミット、プッシュ、プルでリモートリポジトリを経由します。

サーバーレスコンピュートの課金と実行主体を考えれば当然といえば当然の設計ですが、「共有」という言葉から共同編集環境を想像すると認識がずれます。共有されるのは1人のユーザーの中での複数ファイル間、という理解が正確です。

制限事項

現時点で挙がっている制限は1つです。

コンピュートの共有はサーバーレス使用ポリシーの範囲にスコープされる。同じGitフォルダのノートブックやファイルでも、異なる使用ポリシーを使っている場合は、共有ではなく別々のコンピュートリソースが割り当てられる

使用ポリシーは課金の帰属先を決めるものなので、帰属先の違うワークロードが1つのコンピュートに同居しないようにしている、ということだと思われます。ポリシーを使い分けているワークスペースでは、意図せず別コンピュートが立ち上がることがあるので、コンピュートが共有されていないと感じたらここを疑うとよさそうです。

まとめ

Git Folder Serverlessを試して分かったことをまとめます。

Gitフォルダ内のノートブックとファイルが、1つのサーバーレスコンピュートと1つの環境を共有する
環境の定義はGitフォルダのルートの pyproject.toml。ノートブックごとの環境サイドパネル設定とは別の仕組み
使うにはGitフォルダエディタで開く必要がある。通常のノートブック画面からは選べない
%uv add で依存関係を追記し、%uv sync で共有環境に適用して uv.lock を生成・更新する
pyproject.toml を直接編集した場合は、エディタ上部の「適用」をクリックする
既存の pyproject.toml がある場合、environment_version は5以降にする
共有されるのはコンピュートと環境だけで、Python変数は別のノートブックから参照できない
コンピュートを実行できるのは起動したユーザーのみ。共同作業では各自がクローンする
使用ポリシーが異なるとコンピュートは共有されない

一番の収穫は、環境の定義がノートブックのメタデータからリポジトリのファイルに移ったことでした。ノートブックの環境設定はそのノートブックを開かないと分からず、レビューの対象にもなりませんでしたが、pyproject.toml と uv.lock になればGitの流儀で扱えます。複数のノートブックで構成されるプロジェクトを、ソフトウェアプロジェクトとして扱いやすくなる方向の変化だと感じています。ベータなので今後変わる可能性はありますが、この方向自体は歓迎したいところです。