uvを使ったdbt Coreの導入手順

dbt公式の手順では、

• Docker
• pip
• source

でのdbt Core導入手順が掲載されています。
本記事ではuvを用いたdbt Core導入手順を紹介します。

Requirements

• macOS 14.5
• Apple M1+ CPU (not Intel Mac)
• zsh

Windows OSは未検証です。
Windows OSの環境で導入したい場合は、OS依存している箇所(e.g. ディレクトリ構成)を適宜読み替えて実施してみてください。
ただし、その際の動作保証は致しかねます。

Setup

本手順ではTerminal.app(macOS標準), Visual Studio Codeの利用を前提としています。
上記以外のターミナルエミュレーター(e.g. iTerm2, Hyper)でも導入手順の実施はできるかと思いますが、動作保証は致しかねます。

コマンドシェルはmacOS 10.15以降から標準シェルとなったzshを使用します。
bash, fishは未検証です。

Homebrew settings

Install Homebrew

Homebrewをインストールします。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install packages for macOS

uvをインストールします。

brew install uv

misc.

今回は省略しましたが、初回環境構築時ではこのタイミングでGit, GitHub CLIをインストールすることが多いです。

brew install git gh

uv settings

本手順では以下のディレクトリ構成で説明します。異なるディレクトリ構成にしたい、適宜読み替えてください。

~/Development
    ┗ example-dbt-project

Create dbt Project directory

dbt Projectのディレクトリを作成します。

mkdir ~/Development
cd ~/Development
uv init example-dbt-project --bare

Install Python with uv

2025-05-05現在、Python 3.13系の最新バージョンを確認します。

uv python list --all-versions | grep -e "3\.13\."

# Results
# cpython-3.13.3-macos-aarch64-none                   <download available> <- target version
# cpython-3.13.3+freethreaded-macos-aarch64-none      <download available>
# cpython-3.13.2-macos-aarch64-none                   <download available>
# cpython-3.13.2+freethreaded-macos-aarch64-none      <download available>
# cpython-3.13.1-macos-aarch64-none                   <download available>
# cpython-3.13.1+freethreaded-macos-aarch64-none      <download available>
# cpython-3.13.0-macos-aarch64-none                   <download available>
# cpython-3.13.0+freethreaded-macos-aarch64-none      <download available>

Python 3.13系の最新バージョンをインストールします。

# Template
uv python install <latest-version-of-python-3.13-series>

# e.g.
uv python install 3.13.3

Pin to a specific Python version

Pythonバージョンを固定します。

cd ~/Development/example-dbt-project
uv python pin 3.13.3

Install Python packages

dbt関連のPythonパッケージをインストールします。
データ環境はBigQueryを使用します。

cd ~/Development/example-dbt-project
uv add dbt-core dbt-bigquery

[Optional]Install Python packages for development

SQLFluffなど、開発に関するPythonパッケージは、開発依存パッケージとして別でインストールします。
この対応で、本番環境にデプロイ時に開発依存パッケージを除外することができます。

cd ~/Development/example-dbt-project
uv add --dev sqlfluff sqlfluff-templater-dbt

Create virtual environment(.venv)

仮想環境を作成します。

cd ~/Development/example-dbt-project
uv sync

以上までの手順で、ディレクトリ、ファイルは以下の構成となります。

~/Development
    ┗ example-dbt-project
        ┣ .venv/          : 仮想環境
        ┣ .python-version : Pythonバージョンを管理するファイル
        ┣ pyproject.toml  : Python構成ファイル
        ┗ uv.lock         : プロジェクトの依存関係を管理するロックファイル

Execute dbt command

Without activating virtual environment

仮想環境を起動せずに仮想環境下のコマンドを実行する場合は、 uv run を使用します。
単発でコマンドを実行する場合に役に立ちます。
以下は仮想環境を起動せずにdbtのバージョンを確認した例です。

cd ~/Development/example-dbt-project

# check dbt version
uv run dbt -V

# Results
# Core:
#   - installed: 1.9.4
#   - latest:    1.9.4 - Up to date!
# 
# Plugins:
#   - bigquery: 1.9.1 - Up to date!

Activate virtual environment

仮想環境を起動すると、ターミナル操作と同様のコマンドを実行できます。
コマンドを連続で実行する場合に役に立ちます。
以下は仮想環境を起動後、dbtのバージョンを確認した例です。

cd ~/Development/example-dbt-project

# Activate virtual environment
. .venv/bin/activate

# Check dbt version
dbt -V

# Results
# Core:
#   - installed: 1.9.4
#   - latest:    1.9.4 - Up to date!
# 
# Plugins:
#   - bigquery: 1.9.1 - Up to date!

Deactivate virtual environment

仮想環境を停止したい場合は、以下を実施します。

# Deactivate virtual environment
deactivate

Initialize dbt project

初めてdbtプロジェクトを作成する場合は、以下を実施します。

# Template
cd <any directory>
uv run dbt init <dbt_project_name> --profiles-dir ./

# e.g.
cd ~/Development/example-dbt-project
uv run dbt init example_dbt_project --profiles-dir ./

2025-12-05現在、 dbt init は任意のディレクトリにdbtプロジェクトを作成できません。
これは git init , uv init などのコマンドの挙動と異なるという指摘を受けておりますが、改修の目処は立っていません。
詳細は以下を参照してください。

• https://github.com/dbt-labs/dbt-core/issues/1121
• https://github.com/dbt-labs/dbt-core/issues/4141
• https://github.com/dbt-labs/dbt-core/issues/8216

cf. 挙動確認と回避方法

# dbt init前後の変化
## 1. dbt init実施前のディレクトリ構造
# ~/Development
#     ┗ example-dbt-project
#         ┣ .venv/          : 仮想環境
#         ┣ .python-version : Pythonバージョンを管理するファイル
#         ┣ pyproject.toml  : Python構成ファイル
#         ┗ uv.lock         : プロジェクトの依存関係を管理するロックファイル

## 2. 期待するディレクトリ構造
# ~/Development
#     ┗ example-dbt-project
#         ┣ .venv/          : 仮想環境
#         ┣ analyses/       : dbt initで生成されたディレクトリ
#         ┣ logs/           : dbt initで生成されたディレクトリ
#         ┣ macros/         : dbt initで生成されたディレクトリ
#         ┣ models/         : dbt initで生成されたディレクトリ
#         ┣ seeds/          : dbt initで生成されたディレクトリ
#         ┣ snapshots/      : dbt initで生成されたディレクトリ
#         ┣ tests/          : dbt initで生成されたディレクトリ
#         ┣ .python-version : Pythonバージョンを管理するファイル
#         ┣ dbt_project.yml : dbt initで生成されたファイル
#         ┣ profiles.yml    : dbt initで生成されたファイル
#         ┣ pyproject.toml  : Python構成ファイル
#         ┣ uv.lock         : プロジェクトの依存関係を管理するロックファイル
#         ┗ README.md       : dbt initで生成されたファイル

## 3. dbt init実施
cd ~/Development/example-dbt-project
uv run dbt init example_dbt_project

# ~/Development
#     ┗ example-dbt-project
#         ┣ .venv/                : 仮想環境
#         ┣ example_dbt_project   : dbt initで生成されたプロジェクトルートディレクトリ
#         ┃    ┣ analyses/       : dbt initで生成されたディレクトリ
#         ┃    ┣ macros/         : dbt initで生成されたディレクトリ
#         ┃    ┣ models/         : dbt initで生成されたディレクトリ
#         ┃    ┣ seeds/          : dbt initで生成されたディレクトリ
#         ┃    ┣ snapshots/      : dbt initで生成されたディレクトリ
#         ┃    ┣ tests/          : dbt initで生成されたディレクトリ
#         ┃    ┣ .gitignore      : dbt initで生成されたファイル
#         ┃    ┣ dbt_project.yml : dbt initで生成されたファイル
#         ┃    ┣ profiles.yml    : dbt initで生成されたファイル
#         ┃    ┗ README.md       : dbt initで生成されたファイル
#         ┣ logs/                 : dbt initで生成されたディレクトリ
#         ┣ .python-version       : Pythonバージョンを管理するファイル
#         ┣ pyproject.toml        : Python構成ファイル
#         ┗ uv.lock               : プロジェクトの依存関係を管理するロックファイル

## 4. 2のディレクトリ構造に変更するために以下を実施
cp -r ./example_dbt_project/* 
rm -rf example_dbt_project

以上でuvを利用したdbt Coreの導入は完了です。
このあとはデータ接続環境に合わせてdbt環境の構築を実施してください。
(以下、主要な接続先の環境構築手順を載せておきます。)

• BigQuery
• Snowflake
• Redshift
• Databricks
• DuckDB

Update components

uv

uvのバージョンを最新に更新します。

# 実行場所はどこでもOK
brew update
brew upgrade

Python

Pythonのバージョンは .python-version で管理しています。
PythonのバージョンアップはInstall Python with uvおよびPin to a specific Python versionと同様の手順を実施します。

# Search the latest version of Python
uv python list --all-versions | grep -e "3\.13\."

## Results(as of December 5, 2025)
# cpython-3.13.10-macos-aarch64-none                  <download available> <- target version
# cpython-3.13.10+freethreaded-macos-aarch64-none     <download available>
# cpython-3.13.9-macos-aarch64-none                   <download available>
# cpython-3.13.9-macos-aarch64-none                   <download available>
# cpython-3.13.9+freethreaded-macos-aarch64-none      <download available>
# cpython-3.13.8-macos-aarch64-none                   <download available>
# cpython-3.13.8+freethreaded-macos-aarch64-none      <download available>
# ...

# Install the latest version of Python
uv python install 3.13.10

# Pin to the latest version of Python
cd ~/Development/example-dbt-project
uv python pin 3.13.10

仮想環境(.venv)が存在する場合は、仮想環境のPython Interpreterのバージョンを更新する必要があるので以下を実施します。

# Template
uv venv --python <latest-version-of-python-3.13-series>

# e.g.
uv venv --python 3.13.10

Python packages

Pythonパッケージは pyproject.toml uv.lock で管理しています。
仮想環境のPython Interpreterの更新をした場合やPythonパッケージのバージョンアップをしたい場合は、以下のコマンドを実行します。

cd ~/Development/example-dbt-project
uv lock --upgrade
uv sync

Troubleshooting

dbtコマンドが実行できない

1. Python Interpreterの設定

Visual Studio Codeの場合、Python Interpreterの設定がおかしい場合があります。
.venv/bin/python を参照するようにPython Interpreterの設定を変えてみてください。

2. Pythonバージョン不一致

uvでインストールしたPythonバージョンと仮想環境が参照しているPythonバージョンが不一致の可能性があります。
以下を実施して不一致を解消します。

# Template
uv venv --python <latest-version-of-python-3.13-series>
uv sync

# e.g.
cd ~/Development/example-dbt-project
uv venv --python 3.13.3
uv sync

3. 仮想環境を作り直す

上記手順でも改善しない場合は、仮想環境の再構築を試してみてください。

cd ~/Development/example-dbt-project

# 仮想環境を削除し、空の状態で作成し直す
uv venv

# Pythonパッケージを再インストールする
uv sync

APPENDIX

• Homebrew
• uv
• About dbt Core setup
• Visual Studio Code - Manually specify an interpreter