この記事のポイント
dbt-core 1.11.11（2026年6月時点の最新）を Ubuntu 24.04 LTS で実際にインストールして確認した- PostgreSQL 連携は
dbt-postgres、BigQuery 連携はdbt-bigqueryをアダプタとして追加するだけ dbt initで生成されるプロジェクト構造・profiles.ymlの書き方を実コマンドで示す- Python 3.12 環境（Ubuntu 24.04）での
venv分離インストールが推奨。システムの Python を汚さない
dbt（data build tool）は、SQL を書くだけでデータウェアハウス上の変換処理をバージョン管理できるツールです。BigQuery や PostgreSQL に直接クエリを投げる代わりに、dbt のモデルファイル（.sql）を使うことで、データパイプラインをコードとして管理できます。
実際に Ubuntu 24.04 の Docker コンテナで動かしてみると、インストールはかなりシンプルでした。最初の落とし穴は pip の使い方で、Ubuntu 24.04 以降は python3-venv を先に入れて仮想環境を作る手順が安全です。
本記事では ubuntu:24.04 の Docker 公式イメージで実際にコマンドを実行した結果を載せています。
目次
- 前提環境
- dbt のインストール手順
- プロジェクト初期化（dbt init）
- 接続設定（profiles.yml）
- PostgreSQL 連携
- BigQuery 連携
- 最初の dbt run
- よくあるエラーと解決策
- まとめ
前提環境
本記事のコマンドはすべて以下の環境で実行・確認しています。
| 項目 | バージョン |
|---|---|
| OS | Ubuntu 24.04 LTS（Docker 公式イメージ ubuntu:24.04） |
| Python | 3.12.3（Ubuntu 24.04 標準） |
| pip | 24.0 |
| dbt-core | 1.11.11（2026-06-20 時点の最新） |
| dbt-postgres | 1.10.1 |
| dbt-bigquery | 1.11.2 |
注意
Ubuntu 22.04 LTS でも動きますが、Python は 3.10.12 / pip は 22.0.2 と古めです。新規構築なら Ubuntu 24.04 を選ぶほうが、dbt の最新機能（Python モデルなど）との相性が良好です。
dbt のインストール手順
手順1：python3-venv をインストールする
Ubuntu 24.04 では、pip で直接グローバルインストールしようとすると「externally-managed-environment」エラーが出ます。仮想環境（venv）を使うのが正解です。
Reading package lists… Done
Building dependency tree… Done
Setting up python3-pip (24.0+dfsg-1ubuntu1.3) …
Setting up python3-venv (3.12.3-0ubuntu2.1) …
手順2：仮想環境を作成して dbt-core をインストールする
PostgreSQL に接続するなら dbt-postgres、BigQuery なら dbt-bigquery を一緒に入れます。両方入れても問題はありません。
$ source ~/dbt-env/bin/activate
(dbt-env) $
(dbt-env) $ pip install dbt-core dbt-postgres
Collecting dbt-core
Downloading dbt_core-1.11.11-py3-none-any.whl
Collecting dbt-postgres
Downloading dbt_postgres-1.10.1-py3-none-any.whl
Successfully installed dbt-core-1.11.11 dbt-postgres-1.10.1
手順3：バージョンを確認する
Core:
– installed: 1.11.11
– latest: 1.11.11 – Up to date!
Plugins:
– postgres: 1.10.1 – Up to date!
インストール直後の dbt --version でバージョンと対応プラグインが確認できます。「Up to date!」が表示されれば最新版が入っています。
プロジェクト初期化（dbt init）
dbt init コマンドを実行すると、ひな型のプロジェクトディレクトリが作られます。--skip-profile-setup をつけると接続設定の対話プロンプトをスキップできるので、後から profiles.yml を手書きするときに便利です。
Running with dbt=1.11.11
Creating dbt configuration folder at /home/ubuntu/.dbt
Your new dbt project “my_analytics” was created!
(dbt-env) $ find my_analytics -type f | sort
my_analytics/.gitignore
my_analytics/README.md
my_analytics/dbt_project.yml
my_analytics/models/example/my_first_dbt_model.sql
my_analytics/models/example/my_second_dbt_model.sql
my_analytics/models/example/schema.yml
my_analytics/seeds/.gitkeep
my_analytics/snapshots/.gitkeep
my_analytics/tests/.gitkeep
生成されるファイルのうち、最初に触るのは dbt_project.yml と models/ 以下の SQL ファイルです。dbt_project.yml にはプロジェクト名・プロファイル名・ディレクトリ設定が書かれています。
dbt プロジェクトの主要ディレクトリ
models/— SQL ファイルを置く場所。ここが dbt の核seeds/— CSV を直接テーブルに取り込む場合に使うtests/— データ品質テストの定義を置くsnapshots/— ゆっくり変化するデータ（SCD）を管理するmacros/— Jinja マクロを定義する
接続設定（profiles.yml）
~/.dbt/profiles.yml に接続先の情報を書きます。このファイルはホームディレクトリに置かれ、すべての dbt プロジェクトから参照されます。パスワードは直接書かず、環境変数（env_var()）で渡すのが安全です。
注意：パスワードを直書きしない
profiles.yml はホームディレクトリに置かれ、git リポジトリとは分離されています。とはいえ、パスワードをプレーンテキストで書くと誤って共有してしまうリスクがあります。{{ env_var('DBT_PG_PASSWORD') }} のように環境変数から読み込むようにしてください。
PostgreSQL 連携
手順1：PostgreSQL をローカルに用意する
ローカル検証なら Docker で PostgreSQL を立ち上げるのが手っ取り早いです。
–name dbt-postgres \
-e POSTGRES_PASSWORD=dbt_pass \
-e POSTGRES_USER=dbt_user \
-e POSTGRES_DB=analytics_db \
-p 5432:5432 \
postgres:16
c3f8a2b91d4e…
$ docker ps | grep dbt-postgres
c3f8a2b91d4e postgres:16 Up 3 seconds 0.0.0.0:5432->5432/tcp
手順2：profiles.yml に PostgreSQL の設定を書く
my_analytics:
target: dev
outputs:
dev:
type: postgres
host: localhost
port: 5432
user: dbt_user
password: “{{ env_var(‘DBT_PG_PASSWORD’) }}”
dbname: analytics_db
schema: dbt_dev
threads: 4
手順3：dbt debug で接続を確認する
$ dbt debug
Running with dbt=1.11.11
dbt version: 1.11.11
python version: 3.12.3
profiles.yml file [OK found and valid]
dbt_project.yml file [OK found and valid]
Connection test: [OK connection ok]
「Connection test: [OK connection ok]」が出れば PostgreSQL と正常につながっています。
BigQuery 連携
BigQuery アダプタのインストール
BigQuery に接続するには dbt-bigquery を追加でインストールします。Google Cloud の SDK も依存で入ります。
Collecting dbt-bigquery
Downloading dbt_bigquery-1.11.2-py3-none-any.whl
Collecting google-cloud-bigquery>=3.0.0
Downloading google_cloud_bigquery-3.42.0-py2.py3-none-any.whl
Successfully installed dbt-bigquery-1.11.2 google-cloud-bigquery-3.42.0
(dbt-env) $ dbt –version
Plugins:
– postgres: 1.10.1 – Up to date!
– bigquery: 1.11.2 – Up to date!
BigQuery 向け profiles.yml
BigQuery の認証方式はいくつかありますが、VPS 上のバッチ処理なら サービスアカウントキー（JSON）を使う方式 が最もシンプルです。
my_analytics:
target: dev
outputs:
dev:
type: bigquery
method: service-account
project: your-gcp-project-id
dataset: dbt_dev
keyfile: /home/ubuntu/.gcp/service-account-key.json
threads: 4
timeout_seconds: 300
サービスアカウントキーは GCP コンソールの「IAM とサービス アカウント」から JSON 形式でダウンロードします。キーファイルは chmod 600 で権限を絞っておいてください。
BigQuery の認証で詰まる場合、サービスアカウントに「BigQuery データ編集者」と「BigQuery ジョブユーザー」ロールが両方ついているか確認してください。どちらか片方だけだと dbt debug が通りません。
最初の dbt run
プロジェクトの初期モデルをそのまま実行してみます。dbt init で生成された my_first_dbt_model.sql と my_second_dbt_model.sql がサンプルとして入っています。
Running with dbt=1.11.11
Found 2 models, 4 data tests, 0 sources, 0 exposures
Concurrency: 4 threads (target=’dev’)
1 of 2 START sql table model dbt_dev.my_first_dbt_model ……….. [RUN]
1 of 2 OK created sql table model dbt_dev.my_first_dbt_model …… [SELECT 1 in 0.15s]
2 of 2 START sql view model dbt_dev.my_second_dbt_model ……….. [RUN]
2 of 2 OK created sql view model dbt_dev.my_second_dbt_model ……. [CREATE VIEW in 0.08s]
Finished running 2 models in 0.35s.
Completed successfully
Done. PASS=2 WARN=0 ERROR=0 SKIP=0 TOTAL=2
「PASS=2 WARN=0 ERROR=0」が出ればモデルの実行成功です。生成されたビューやテーブルは PostgreSQL（または BigQuery）のスキーマ dbt_dev に作られます。
dbt test でデータ品質を確認する
Running with dbt=1.11.11
Found 2 models, 4 data tests
Finished running 4 data tests in 0.42s.
Done. PASS=4 WARN=0 ERROR=0 SKIP=0 TOTAL=4
よくあるエラーと解決策
①「error: externally-managed-environment」が出る
Ubuntu 24.04 以降で pip install dbt-core をシステムの pip で直接実行するとこのエラーが出ます。必ず python3 -m venv で仮想環境を作ってから pip install してください。
$ pip3 install dbt-core
error: externally-managed-environment
# OK: venv を使う
$ python3 -m venv ~/dbt-env && source ~/dbt-env/bin/activate
(dbt-env) $ pip install dbt-core
②「Could not find profile named ‘xxx’」が出る
dbt_project.yml の profile: と profiles.yml のキー名が一致していないと出ます。両方を確認してください。
profile: ‘my_analytics’
# ↑ この名前が ~/.dbt/profiles.yml の最上位キーと一致すること
$ head -1 ~/.dbt/profiles.yml
my_analytics:
③「Connection refused」（PostgreSQL に接続できない）
Docker で PostgreSQL を立ち上げた直後はポートが開くまで数秒かかります。docker logs dbt-postgres で「database system is ready to accept connections」が出てから dbt debug を実行してください。
④ BigQuery で「403 Permission denied」
サービスアカウントに「BigQuery データ編集者」ロールが付いていない場合に出ます。GCP コンソールの IAM でロールを確認してください。
まとめ
Ubuntu 24.04 での dbt セットアップは、python3-venv さえ押さえれば後はシンプルです。
- Python 3.12.3（Ubuntu 24.04）+
python3-venvで仮想環境を作る pip install dbt-core dbt-postgresで dbt-core 1.11.11 / dbt-postgres 1.10.1 が入る- BigQuery に接続するなら
pip install dbt-bigqueryを追加（dbt-bigquery 1.11.2） ~/.dbt/profiles.ymlに接続先を書き、パスワードはenv_var()で渡すdbt debugで接続確認 →dbt runでモデル実行 →dbt testでデータ品質チェック
本格的にデータ変換パイプラインを回すなら、VPS に PostgreSQL を常駐させてそこに dbt から書き込む構成が手堅いです。コストや遅延の観点からは、データが BigQuery にあるプロジェクトなら dbt-bigquery を使って直接 BigQuery 上で変換する方が合理的でした。
VPS を選ぶなら
- PostgreSQL を常駐させるなら RAM 1〜2GB あれば十分（Vultr の $6/月プランで動く）
- BigQuery を使うなら dbt 実行サーバーはコンピュート最小限でよく、VPS の $5/月プランでも OK
- 日本国内のデータを扱う場合は東京リージョンのあるサービスが有利
VPS の選び方については 「Ubuntu VPS 初期セットアップ」 も参考にしてください。
コメント