Installation & Setup¶

Get dbt Charts installed and configured in your environment.

Prerequisites¶

Before installing dbt Charts, ensure you have:

Python 3.11+ installed
A database dbt Charts can query: DuckDB, SQLite, Postgres, Snowflake, BigQuery, Redshift, Databricks, Spark, Trino, Athena, ClickHouse, or a local CSV/Parquet file. See Warehouse adapters

dbt Charts works with plain SQL, so dbt is optional. If you already run dbt, dbt Charts can read your profiles.yml connection and query dbt-modeled tables directly. But you don't need dbt to build dashboards.

Installation¶

Install dbt Charts¶

Install with uv (recommended) or pip. If you have neither yet, both of those pages cover Windows, macOS, and Linux.

# with uv (recommended); installs dct as a standalone CLI tool
uv tool install dbt-charts

# with pip
pip install dbt-charts

uv tool install is not the same as uv pip install dbt-charts. uv tool install creates an isolated environment for the dct CLI and puts a shim on your PATH (via ~/.local/bin), independent of any project virtualenv: the closest uv equivalent to a global pip install. uv pip install dbt-charts instead installs dbt Charts into the currently active virtualenv, the way pip install does; reach for that only when you want to import dbt_charts from your own project code, not when you just want the dct command available everywhere.

If you build with dbt v2, use uv tool install (or pipx) and never install dbt Charts into the environment that holds dbt v2. dbt v2 and dbt Core 1.x share the dbt-core package name, and the warehouse adapters dbt Charts uses depend on 1.x, so a shared environment ends with dbt v2 silently replaced. See Using dbt Charts with dbt v2.

To use dct mcp serve (the MCP server for external AI agents), dbt Charts needs the optional mcp extras. If you run it without them installed, dbt Charts will detect the missing packages and offer to install them interactively. For non-interactive setups (CI, scripts), set DCT_NO_AUTO_INSTALL=1 to suppress the prompt and get a clear error with the exact install command instead.

dct playground opens the hosted playground at play.dbtcharts.com in your browser; no extra install required.

Warehouse adapters¶

dbt Charts opens its own connection to your database, through a Python adapter package. DuckDB and SQLite work out of the box. For every other warehouse, install the matching extra:

Warehouse	Extra
DuckDB, SQLite	included, nothing to install
Snowflake	`dbt-charts[snowflake]`
BigQuery	`dbt-charts[bigquery]`
Postgres	`dbt-charts[postgresql]`
Redshift	`dbt-charts[redshift]`
Databricks	`dbt-charts[databricks]`
Spark	`dbt-charts[spark]`
Trino	`dbt-charts[trino]`
Athena	`dbt-charts[athena]`
ClickHouse	`dbt-charts[clickhouse]`
Lake compute	`dbt-charts[lakecompute]`
SQL Server	`dbt-charts[sqlserver]`, plus Microsoft ODBC Driver 17 or 18 on the host
Microsoft Fabric	`dbt-charts[fabric]`, plus Microsoft ODBC Driver 17 or 18 on the host

Use the same installer you installed dbt Charts with. uv tool install creates an isolated environment for the dct CLI, and a later pip install cannot add anything to it:

# if you installed the dct CLI with uv tool install
uv tool install "dbt-charts[snowflake]"

# if you installed dbt Charts into a virtualenv
pip install "dbt-charts[snowflake]"

Quote the argument either way: unquoted, the square brackets are shell glob characters.

dbt Charts uses the adapter as a library for its own queries and never invokes the dbt command. Each adapter depends on dbt Core 1.x, which is invisible in an isolated dct environment but replaces dbt v2 when both share one environment. If you build with dbt v2, see Using dbt Charts with dbt v2.

Verify Installation¶

dct --version

You should see the dbt Charts version number.

Install the Editor Extension¶

If you author dashboards in VS Code or Cursor, install the dbt Charts extension: it adds board YAML highlighting, snippets, and a live preview of the rendered dashboard beside your file:

dct init code      # VS Code
dct init cursor    # Cursor

See the VS Code & Cursor Extension page for everything it provides and how to install it without the CLI.

Upgrading¶

dbt Charts separates package upgrade (the Python wheel) from project refresh (workflow skill files copied into your repo). This matches how dbt, gh, and npx skills handle upgrades: pip bumps the tool; a separate command refreshes project-local artifacts.

1. Upgrade the package¶

pip install -U dbt-charts
# or, with uv:
uv pip install -U dbt-charts

Confirm which install is active:

dct --version

2. Refresh project artifacts¶

After upgrading the package:

dct init skills

Re-syncs skill directories (installed under a dct- prefix, for example, dct-chart/). Retired skills are removed; current skills are always overwritten in place, no flag needed.

Targeted installs:

dct init skills agents          # .agents/skills/ (Cursor, Codex, Copilot)
dct init skills claude          # Claude Code skills directory
dct init skills --dir PATH      # custom path

Re-run after pip install -U dbt-charts to pull in skills added by the new release.

Configuration¶

Connect a Data Source¶

Name the database dbt Charts reads from in dbt_charts.yml. A local DuckDB file needs no credentials, so it's the quickest way to start:

# dbt_charts.yml
sources:
  analytics:
    type: duckdb
    path: ./data/analytics.duckdb

Direct source types (postgres, snowflake, bigquery, redshift, sqlite) use the same credential fields as dbt profiles. See Sources for every type and its connection settings.

Using dbt? Inside a dbt project you can skip this step: with no sources: declared, dbt Charts reuses the connection of the profile: named in dbt_project.yml, and SQL queries need no source:. To declare it yourself, set type: dbt_profile (this also turns the automatic source off):

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

Create Charts Directory¶

Create a directory for your dashboards (called "charts" in dbt Charts):

mkdir charts

Place your dashboard YAML files in this directory. The charts/ directory is the canonical location for all dbt Charts dashboard files. The CLI defaults to this directory for validate, serve, and render commands.

Project Configuration (Optional)¶

dbt Charts supports project-wide configuration via a dbt_charts.yml file in your project root.

What belongs in dbt_charts.yml: engine knobs: data sources, server port, execution settings. The model rejects unknown keys, so presentation keys (theme:, frame:, style:) raise a clear error here; they belong in charts/meta.yml.

# dbt_charts.yml: engine knobs only
server:
  port: 8080

sources:
  my_db:
    type: duckdb
    path: data.duckdb

Execution settings¶

The execution: block controls query parallelism and timeouts:

# dbt_charts.yml
execution:
  max_workers: 8
  max_query_duration_seconds: 300

max_workers: maximum parallel query workers per render. Effective only for external warehouse executors (BigQuery, Snowflake, Postgres, etc.); DuckDB and SQLite serialize access internally regardless of this setting. Also settable per-run via --max-workers on dct render / dct serve, or the DCT_MAX_WORKERS env var.
max_query_duration_seconds: the safety ceiling on how long a single query may run, enforced as a server-side statement timeout on network warehouses. DuckDB and SQLite are local file databases with no server to enforce a timeout, so this has no effect on them. Override per source with sources.<name>.max_query_duration_seconds:

# dbt_charts.yml
sources:
  analytics:
    type: snowflake
    max_query_duration_seconds: 60

Server settings¶

server.markdown_metadata_table renders non-board frontmatter keys in .md files as a metadata table at the top of the page. Off by default, so AGENTS.md, README, and other prose files served through dbt Charts don't suddenly acquire header tables:

# dbt_charts.yml
server:
  markdown_metadata_table: true

Cloud settings¶

The cloud: block holds rules that dbt Charts Cloud applies to the project. It can only tighten: false turns a capability off for the project, and leaving a key out or setting it to true defers to the switches on the Cloud project settings page.

# dbt_charts.yml
cloud:
  allow_public: false
  honor_agent_instructions: false

allow_public: false: nothing in the project is served to people outside the organization, even when the organization and project public-access switches are on. See Public access.
honor_agent_instructions: false: the AI copilot ignores the repository's AGENTS.md, CLAUDE.md, and skills/ folders, even when the Agent settings checkbox is on.

Cloud reads this block from the project's work branch, not the branch you are viewing, so a change branch cannot loosen it. Cloud checks the whole file: an unknown or repeated key, or a value that is not true or false, is an error rather than a switch left on, and the settings page notes when the file is overriding a switch.

What belongs in charts/meta.yml: board layout and other presentation defaults. meta.yml is a partial board that applies as a cascade base to every board in its directory.

# charts/meta.yml: presentation defaults
style:
  frame:
    max_width: 1440.0     # Widest boards may auto-size to (default: 1200.0)
    card_padding: 20.0

Configuration Discovery: - dbt Charts searches for dbt_charts.yml starting from the current working directory and walks up to the filesystem root. - If you're working in a dbt project, dbt Charts also detects dbt_project.yml as a project root indicator. - If no dbt_charts.yml is found, built-in defaults are used.

These settings apply to all dashboards in your project unless overridden in individual dashboard YAML files.

Adding dbt Charts to an Existing dbt Project¶

If you already have a dbt project, adding dbt Charts takes three steps:

cd my-dbt-project

# 1. Install dbt Charts (see the Installation section above)

# 2. Bootstrap the project; creates charts/, dbt_charts.yml, and workflow skills
dct init

# 3. Serve the project; with no board yet it shows an intro page
dct serve

dct init creates charts/ with a meta.yml; it writes no board. It also installs workflow skills for local AI assistants unless you pass --no-skills. Open the URL dct serve prints: until your first board exists, it shows an intro page.

Your dbt project should now look like this:

my-dbt-project/
├── dbt_project.yml          # dbt config (existing)
├── models/                  # dbt models (existing)
├── profiles.yml             # dbt profiles (existing)
├── dbt_charts.yml           # Optional: engine knobs (sources, server port, etc.)
├── .agents/skills/          # Workflow skills for Cursor, Codex, and Copilot
├── charts/                  # dbt Charts dashboards
│   ├── meta.yml             # Board-wide defaults
│   ├── sales_dashboard.yml
│   └── partials/            # Reusable dashboard fragments (prefixed with _)
│       └── _header.yml
└── assets/                  # Optional: images, CSV data files
    ├── images/
    └── data/

Key conventions: - charts/ is the canonical directory for all dashboard YAML files. The dct CLI defaults to this directory. - Partials live in charts/partials/ and are prefixed with _ (for example, _header.yml). They're reusable fragments imported by other dashboards. - Subdirectories are fine: charts/sales/overview.yml maps to the URL /charts/sales/overview/ when served. - dbt_charts.yml is optional; it sets engine knobs (sources, server port, execution config). Place it next to dbt_project.yml. Board layout and other presentation defaults belong in charts/meta.yml instead.

dbt Charts reads your dbt project automatically. When you run dct serve or dct validate inside a dbt project directory, dbt Charts discovers dbt_project.yml and connects to your database via profiles.yml. Your queries hit models with plain SQL.

Verification¶

Test Installation¶

Create a simple dashboard file charts/test.yml:

title: "Test Dashboard"

queries:
  test:
    rows:
      - month: "2024-01"
        revenue: 12000
      - month: "2024-02"
        revenue: 15400
      - month: "2024-03"
        revenue: 11800

charts:
  test_chart:
    title: "Revenue by Month"
    query: test
    type: bar
    x: month
    y: revenue

rows:
  - test_chart

Validate the dashboard:
```
dct validate charts/test.yml
```
Preview the dashboard:
```
dct serve
```
Open your browser to the URL printed by dct serve on startup

If you see the dashboard, installation is successful!

Troubleshooting Common Issues¶

Warehouse Adapter Not Installed¶

Error: ERR-ADAPTER-NOT-INSTALLED, from a type: dbt_profile source or a direct source alike. dct init prints the same text as a Tip: when it detects a dbt project whose profile needs a missing adapter:

ERR-ADAPTER-NOT-INSTALLED  dbt Charts needs the dbt-snowflake adapter to query
'snowflake' sources, and it is not installed in this Python environment.
Install it with: uv tool install "dbt-charts[snowflake]"

Solution: Run the command the error names. It matches how dbt Charts was installed:

uv tool install "dbt-charts[snowflake]"   # or: pip install "dbt-charts[snowflake]"

See Warehouse adapters for every warehouse and its extra. This is about dbt Charts' own database connection, not your dbt installation; it appears whether you build with dbt v1 or dbt v2.

dbt Downgraded to 1.x After Installing dbt Charts¶

Error: dbt --version reports Core 1.x and dbt v2 is gone.

Cause: dbt Charts was installed into the environment that holds dbt v2. Its warehouse adapter depends on dbt-core 1.x, and pip replaced v2 to satisfy it.

Solution: Remove dbt Charts from that environment, reinstall dbt v2, and install dbt Charts as a tool instead. Steps in Using dbt Charts with dbt v2.

Database Connection Issues¶

Error: Cannot connect to database

Solution: - Check your profiles.yml configuration - Verify database credentials - Test dbt connection: dbt debug

YAML Syntax Errors¶

Error: YAML parsing errors

Solution: - Check YAML indentation (use spaces, not tabs) - Validate YAML syntax with a YAML validator - Use dct validate to check for errors

AI / MCP Setup for IDEs¶

To use dbt Charts from the Claude or ChatGPT app, you don't need any of this: add the hosted Claude & ChatGPT connector instead. A coding agent with a shell is best served by the dct CLI itself; see CLI and MCP for AI assistants.

dbt Charts also includes a local MCP (Model Context Protocol) server for editor agents that can't run shell commands, such as VS Code / GitHub Copilot agent mode. To configure your IDE:

# Auto-detect installed AI clients and configure all of them
dct init mcp

# Or configure a specific client
dct init mcp cursor     # Cursor
dct init mcp vscode     # VS Code / GitHub Copilot
dct init mcp claude     # Claude Desktop
dct init mcp codex      # OpenAI Codex CLI
dct init mcp claude-code # Claude Code (.mcp.json)

This writes the appropriate MCP config file for each client (for example, .cursor/mcp.json, .vscode/mcp.json). After running this, your AI assistant can: - Execute queries against your database (execute_sql tool), including INFORMATION_SCHEMA queries to browse tables and columns - Render dashboards from YAML (render_board tool) - Search existing dashboards (search_files tool)

Tip: Run dct init mcp after cloning any repo that uses dbt Charts; it auto-detects which AI clients you have installed.

Manual Setup¶

If you prefer to configure manually, add the dbt Charts MCP server to your client's config.

For JSON-based clients (Cursor, VS Code, Claude Desktop, Claude Code, Copilot):

{
  "mcpServers": {
    "dbt-charts": {
      "command": "dct",
      "args": ["mcp", "serve"]
    }
  }
}

For Codex (TOML: .codex/config.toml):

[mcp_servers.dbt-charts]
command = "dct"
args = ["mcp", "serve"]

If your dbt Charts or dbt project lives in a subdirectory of the workspace your AI client opens, append "--project-dir", "/abs/path/to/your/project" to args so the server starts in the right place. dct init mcp adds this for you when you pass --project-dir <path> or when it detects that the workspace and project roots diverge.

Config file locations: - Cursor: .cursor/mcp.json - VS Code / Copilot: .vscode/mcp.json (use "servers" instead of "mcpServers") - Claude Desktop: ~/.config/claude/config.json - Claude Code: .mcp.json (project root) - Codex CLI: .codex/config.toml (TOML; project must be trusted by Codex). For global setup, write to ~/.codex/config.toml instead.

Starting the MCP Server Manually¶

dct mcp serve

This starts the MCP server in stdio mode (for IDE integration). It also starts an embedded HTTP server on port 8765 for dashboard preview rendering.

Next Steps¶

Getting Started Guide - Create your first dashboard
CLI Reference - Complete CLI command reference (validate, render, serve, schema, and more)
Queries Guide - Learn about queries
Examples - See example dashboards

Using dbt Charts with dbt v2 - dbt v2 compatibility and setup
Troubleshooting Guide - Common installation and setup issues
Best Practices Guide - Dashboard design best practices

Getting Help¶

If you encounter issues:

Check the Troubleshooting Guide
Check your dashboard: dct validate
Check dbt configuration: dbt debug
Review the YAML Schema Reference