Zenn
📝

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

に公開
Python
dbt
uv
tech

dbt公式の手順では、

  • Docker
  • pip
  • source

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

Requirements

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

Setup

Homebrew settings

Install Homebrew

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

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

Install packages

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

brew install uv

uv settings

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

お好みでdbt開発で使用するPythonパッケージをインストールします。

cd ~/Development/example-dbt-project
uv add --dev dbt-osmosis 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 .venv

仮想環境をアクティベートしないでdbtのバージョンを確認してみます。

cd ~/Development/example-dbt-project
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!

activating .venv

仮想環境をアクティベートしてdbtのバージョンを確認してみます。

cd ~/Development/example-dbt-project
. .venv/bin/activate
dbt -V

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

以上でdbt Coreのセットアップは完了です。このあとはデータ環境に合わせてdbt環境の構築を実施してください。
(以下、主要なData Warehouseのdbt環境構築手順を載せておきます。)

Update components

uv

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

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

Python

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

Python packages

Pythonパッケージは pyproject.toml uv.lock で管理しています。
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

Discussion