How to Visualize dbt Project Dependencies: A Step-by-Step Guide

You want to see how your dbt project fits together, not read it file by file. This guide takes you from an empty browser tab to a shareable dependency graph in about five minutes. You do not need dbt installed, a warehouse login or a manifest file, only the models folder from your repository.

Open the dbt Project Visualizer

What you need before you start

Only your dbt models folder, or a ZIP of the repository. The visualizer reads .sql files as text. Hidden folders, node_modules and target folders are skipped automatically, so build output does not clutter the graph. If your repository includes installed packages, drop just the models folder so package code does not appear as part of your project.

Everything runs in your browser, so the files are not uploaded.

Step 1: add your project

Open the dbt project visualizer. Drag your models folder onto the drop area, or use Select folder or Browse files. You can also drop a ZIP. A small pop-up shows how many SQL files were read and how many were skipped.

If you just want to see the controls first, pick the dbt sample project on the page. It loads a small project in the style of the well-known jaffle shop example.

Step 2: read the graph

Each card is a model or a source. Sources are on the left; staging, intermediate and marts follow in order. The colour reflects the folder, and dashed cards are sources your files read but never create. Under each name you see the type and column count.

An arrow from A to B means B selects from A through ref() or source(). If a model has no incoming arrows it is a starting point, and if it has no outgoing arrows it is a final output or something unused.

Handling a large project

For hundreds of models, do not try to read everything at once. Use the search box to jump to a model or column, zoom out for the overview, or click one model and choose Both so only its neighbourhood is drawn.

Step 3: follow dependencies from one model

Click a model. Its connected path turns blue and animated and the rest fades. Then choose a direction:

  • Upstream shows everything the model is built from, all the way back to sources.
  • Downstream shows every model that depends on it, directly or through others.
  • Both shows the whole neighbourhood.

The details bar lists the direct parents and the number of downstream models affected, which answers "what breaks if I change this?" directly. The same idea is explained in more depth in how to identify downstream dependencies before changing SQL.

Step 4: trace a column

Open the Columns tab and choose a model. Each column shows what it is built from and whether it was copied as is or calculated. Click a column to see the full trail back to the source on one side, and the columns that depend on it on the other. Hover a link to read the exact expression, for example a SUM or a CASE.

Column lineage is read from the SQL and is best effort. If a column comes from a macro or a Jinja loop it cannot be traced, and the Issues tab will say so.

Step 5: check the run order and problems

The Run order tab lists your files in the order they could be built, with each file after the files that create the tables it reads. The Issues tab lists circular dependencies and statements that could not be read. Both are good first questions for a team that inherited a project.

Step 6: save or share

Open Export. Save the graph as a PNG or JPG for a document, copy the picture into a slide or ticket, or copy a share link. The link holds the SQL inside the address, so a teammate opens the same graph without anything being stored on a server. For very large projects the link can become too long, in which case use the image export instead.

What the visualizer does not show

Model and column descriptions and the tests declared in your YAML files are shown, but not docs blocks or test results, and Jinja that generates names at run time cannot be followed. Use dbt docs for those details. If you are comparing options, see the best free dbt lineage tools.

Open the dbt Project Visualizer

Related tool pages

  • SQL Lineage Analyzer for a Folder of SQL Files: Upload a folder of SQL files or a dbt project and get table and column lineage across every file, a run order and impact analysis. Free, runs in your browser.
  • dbt Lineage Viewer for Your SQL Models: Drop your dbt models folder and see the lineage graph from sources through staging to marts, with column links. No dbt run, no warehouse. Free, private.
  • SQL Column Lineage Tool: See which source columns build every column of a view or table across many SQL files. Trace to the raw table or forward to dependants. Free, in your browser.
  • SQL File Dependency Analyzer: Find out which SQL file must run before which, from the tables each file creates and reads. Get a run order, circular dependencies and tables nothing uses.
  • SQL Impact Analysis: What Breaks If a Table Changes: Pick a table and see everything downstream that depends on it, and every upstream source it is built from. Works across a whole folder of SQL files, free.
  • SQL File Lineage Tool: Free SQL file lineage tool: drop a folder of .sql files and see which file feeds which table, column by column. Nothing is uploaded.

Also try

How to use the dbt Project Visualizer: step by step

  1. Open the dbt project visualizer and drop your models folder or a ZIP.
  2. Click a model, then choose Upstream, Downstream or Both.
  3. Open Columns to trace a column, then Export to save or share.

When to use the dbt Project Visualizer

  • Learn a dbt project quickly
  • Review a pull request that changes models
  • Document your DAG for the team
  • Find every model a source table feeds

Example

Input: your dbt models/ folder: staging, intermediate and marts

Output: A graph from sources through staging to marts, with every column traced

Frequently asked questions

How do I visualize dbt project dependencies?

Drop your dbt models folder or a ZIP of the project into a dbt visualizer that reads SQL files. It follows ref() and source() and draws the dependency graph in your browser.

What files does the visualizer need?

Your .sql model files, in a folder or a ZIP. It does not need dbt, a manifest.json, a profile or a warehouse connection.

Can I see only the upstream or downstream of one model?

Yes. Click the model and choose Upstream, Downstream or Both. Everything else fades.

How big a project can it handle?

It reads up to 3,000 SQL files of 5 MB each. For very large projects, use search and the Both view to focus on one neighbourhood.

Tip: Put the share link in your pull request description so reviewers can see the dependency graph without cloning the branch.