Setting up dbt locally with VS Code

Installing dbt-bigquery, configuring profiles.yml, and using the dbt Power User extension for VS Code.

Learning Objectives

By the end of this lesson, you will be able to:

  • Install Python and dbt-bigquery on your machine
  • Initialize a local dbt project with dbt init
  • Configure profiles.yml to connect to BigQuery
  • Install and use the dbt Power User extension for VS Code
  • Run dbt commands from the terminal
  • Decide when local dev is the better choice over dbt Cloud

Why dbt locally?

dbt Cloud is great, but local dev gives you:

  • Your own editor and keybindings (this lesson uses VS Code)
  • A terminal where you control versions, dependencies, and shell
  • Faster iteration — no browser round-trips
  • The same toolchain you'd use on a production project at work

The downside is that you do have to install Python, manage a virtual environment, and store warehouse credentials locally. The dbt Power User extension closes most of the experience gap with the Cloud IDE.

Step 1: Install Python

You need Python 3.9 or later. Check what you have:

python3 --version

If it's missing or older than 3.9, install a current version. On macOS the easiest path is Homebrew:

brew install python@3.12

Step 2: Create a virtual environment

A virtual environment keeps dbt and its dependencies isolated from your system Python. From the directory where you want your dbt project to live:

mkdir doe-family-dbt
cd doe-family-dbt
python3 -m venv .venv
source .venv/bin/activate

You'll see (.venv) in your prompt while it's active. Activate it every time you work on the project.

Step 3: Install dbt-bigquery

The dbt adapter for your warehouse is what dbt uses to actually talk to BigQuery. Install it inside the venv:

pip install dbt-bigquery

That pulls in dbt-core and the BigQuery adapter. Verify:

dbt --version

Step 4: Initialize the project

This step assumes you've completed 0.1 Setting up BigQuery and have your project, datasets, and service account JSON key ready.

Scaffold a fresh dbt project:

dbt init doe_family

dbt asks you a few questions:

Prompt Answer
Which adapter? bigquery
Authentication method? service_account (you'll point at the JSON key)
Project ID Your GCP project (e.g., doe-family-dwh)
Dataset doe_family_dev
Service account keyfile Absolute path to the JSON key from Module 0
Threads 4
Location US (or wherever your dataset is)

This creates two things:

  • A new doe_family/ directory with the project skeleton
  • A profiles.yml at ~/.dbt/profiles.yml containing your connection settings

Step 5: Verify the connection

cd doe_family
dbt debug

Look for "All checks passed!". If something fails, the most common culprits are:

  • Wrong path to the service account JSON
  • Service account missing the BigQuery roles (see lesson 1.2)
  • Wrong project ID or dataset

Step 6: Install the dbt Power User extension

Open VS Code, then:

  1. Open the Extensions panel (Cmd/Ctrl+Shift+X)
  2. Search for "dbt Power User" by Innoverio
  3. Install it
  4. Reload the window when prompted

You also want the official Python extension installed; Power User depends on it.

Tell Power User about your venv: open the command palette (Cmd/Ctrl+Shift+P) → "Python: Select Interpreter" → choose the .venv you created in Step 2. Power User uses this to find your dbt install.

What Power User gives you

Feature What it does
Query results Run a model or arbitrary SQL and see results inline
Compiled SQL preview Hover or peek to see Jinja → SQL compilation
Lineage panel Visual DAG of upstream and downstream models
Autocomplete Model names, ref()/source(), column names
Run model from gutter Click ▶ next to a model to run it
Defer to production Compile against prod metadata so you don't have to build everything

These features close the gap between local dev and the dbt Cloud IDE almost completely.

Running your first commands

From the terminal inside your project directory (doe_family/):

dbt debug           # verify connection
dbt run             # run all models
dbt build           # run models + tests (the daily driver)
dbt test            # run tests only
dbt run -s my_model # run a single model

Or use the Power User UI:

  • ▶ icon next to any model definition → runs that model
  • Right-click in the editor → Run This Model
  • Lineage panel → click a node to focus / run

Cloud vs local — when to use each

Situation Better fit
You don't want to install Python dbt Cloud
You want to share a fully hosted environment dbt Cloud
You want scheduled jobs out of the box dbt Cloud
You want full control over Python / dependencies Local
You prefer your own editor and keyboard shortcuts Local
You're iterating very rapidly Local (faster)
You want a free option with zero infra Either works

You can switch between them later — both use the same dbt_project.yml, the same models, and the same warehouse. The only thing that changes is where profiles.yml (or the equivalent connection config) lives.

Hands-On Exercise

  1. Activate the venv, run dbt debug, confirm all checks pass.

  2. Create models/example/jane_says_hi.sql:

    select 'Jane' as name, 'hello from BigQuery' as message

  3. Run it via the terminal: dbt run -s jane_says_hi.

  4. Run it again via the Power User ▶ button next to the model.

  5. Use Power User to view the compiled SQL for the model.

  6. Open the BigQuery console and confirm the table landed in doe_family_dev.

Summary

Concept Key takeaway
Local dbt setup Python venv → dbt-bigquery → dbt init → ~/.dbt/profiles.yml
profiles.yml Where local dbt stores warehouse credentials
dbt Power User VS Code extension by Innoverio; query, preview, lineage, autocomplete
Python interpreter Point Power User at your venv via Python: Select Interpreter
Daily commands dbt build for run+test; -s for selection
Cloud vs local Both produce the same warehouse output; pick on workflow preference

Next Lesson

You now have a local dbt project on disk. Next: put it under version control in 1.5 Git and GitHub.