Skip to content

dbt v2

dbt Charts runs on a dbt v2 project. It reads the artifacts your build produces rather than driving dbt itself, so the engine you build with is not something dbt Charts needs to know about.

One piece of setup is specific to dbt v2: dbt Charts queries your warehouse through a Python adapter package, and that package depends on dbt Core 1.x. Install dbt Charts in its own environment, never in the one that holds dbt v2. Setup explains why.

How dbt Charts uses your dbt project

dbt Charts and dbt v2 do separate jobs against the same project.

dbt v2 builds your models. dbt build, dbt compile, and the rest are untouched: dbt Charts never invokes them, wraps them, or replaces them.

dbt Charts queries the result. dct serve opens its own connection to your warehouse and runs the SQL in your boards.

That second connection is why the adapter matters. dbt Charts is a Python program and connects through a Python adapter package such as dbt-snowflake. dbt v2's adapters are compiled into its binary and cannot be imported from Python, so dbt Charts brings its own.

Everything else already works, because dbt Charts reads your dbt files directly instead of asking dbt to interpret them.

What dbt Charts uses How it reads it
ref() and source() in board queries Reads target/manifest.json as plain JSON
profiles.yml connection details Parses the YAML directly
dbt_project.yml Parses the YAML directly
{{ env_var(...) }} in profiles Resolved using the same rules dbt applies
Board YAML, charts, layout, dct serve Independent of dbt entirely
Connecting to your warehouse Imports a Python dbt-<adapter> package

The manifest reader is version-agnostic by design. It reads a small set of node fields that have been stable across every manifest version, so a dbt v2-written manifest needs no compatibility shim.

Setup

Install dbt Charts as a standalone tool, with the extra for your warehouse:

uv tool install "dbt-charts[snowflake]"

uv tool install gives dct its own private environment and puts only the dct command on your PATH. pipx install "dbt-charts[snowflake]" does the same. See Warehouse adapters for every warehouse and its extra.

Do not pip install dbt-charts into the environment that holds dbt v2. dbt v2 is published on PyPI as dbt-core 2.x, the same package name as dbt Core 1.x. The warehouse adapter dbt Charts uses depends on dbt-core 1.x, and one environment can hold only one version of a package. pip resolves that quietly: it removes dbt v2 and installs Core 1.x in its place. Nothing reports an error, but your next dbt run executes on the old engine.

The isolated install avoids this entirely. dbt Charts reads manifest.json and profiles.yml from disk, so it never needs to share an environment with dbt.

Point dbt Charts at your existing dbt profile:

# dbt_charts.yml
sources:
  analytics:
    type: dbt_profile
    profile: my_dbt_project
    target: prod

Build, then serve:

dbt build      # dbt v2; writes target/manifest.json
dct serve

Boards can now ref() any model dbt v2 built.

Troubleshooting

Missing warehouse adapter

Two messages report this, depending on how the source is configured.

A type: dbt_profile source reports:

Profile 'my_dbt_project' target 'prod': Runtime Error
  Could not find adapter type snowflake!

A direct source (type: snowflake in dbt_charts.yml) reports:

dbt-snowflake is not installed. Install it with: pip install dbt-snowflake

Both mean dbt Charts has no Python adapter for its own connection. Neither is a signal that dbt v1 is required, or that a dbt v2 install is broken or undetected.

Install the extra for your warehouse into the environment dct runs from:

uv tool install "dbt-charts[snowflake]"

An error that survives an install reporting success means the package landed in a different environment than the one dct runs from. Confirm with dct --version and reinstall with uv tool install.

dbt is suddenly version 1.x

dbt --version reports Core 1.x after installing dbt Charts, and dbt v2 is gone. dbt Charts was installed into the same environment as dbt v2, and pip replaced v2 with the Core 1.x that the warehouse adapter depends on. See Setup.

Recover by removing dbt Charts from that environment and installing it as a tool:

pip uninstall dbt-charts dbt-core dbt-snowflake
pip install "dbt-core>=2"           # or however you installed dbt v2
uv tool install "dbt-charts[snowflake]"

Unknown refs

ref() resolves from target/manifest.json. A missing or stale manifest leaves refs unresolved. Build first:

dbt build

dbt parse and dbt compile also write the manifest, for a project you do not want to run in full.

dbt v1

dbt-core 1.x is a dependency of the dbt-charts package and arrives with it. dbt Charts uses it as a library for connection handling and never runs it. In an isolated install it lives inside dct's private environment, exposes no dbt command, and says nothing about which engine builds your project. It only interferes with dbt v2 when both are installed into one environment, which is the case Setup tells you to avoid.