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

Complete 1.2 Setting up BigQuery through the Nexus UI or MCP first. Use its actual project ID and location. Nexus's ingestion login is separate from your local dbt login.

Already working in a managed Nexus client project? Use its existing ~/.dbt/profiles.yml configuration and skip initialization. Do not replace that profile or pass --profiles-dir locally.

For a new personal course project, follow the OAuth authentication section of dbt's BigQuery setup guide to configure Google application-default credentials on your computer. Use a Google identity with access to the project you created in Nexus. The browser login to Nexus does not authenticate local dbt.

Then scaffold your course project:

dbt init doe_family
Prompt Answer
Adapter bigquery
Authentication oauth
Project ID The actual generated project ID from Nexus
Dataset doe_family_dev
Threads 4
Location The same US or EU location selected in Nexus

This creates the project directory and adds its connection settings to ~/.dbt/profiles.yml. Keep any existing profiles in that file.

Your dbt identity needs to run jobs, read source tables, and write models in the development dataset. dbt can create the dataset when that identity has permission; otherwise ask your administrator for access to a prepared development dataset. Nexus's selected ingestion dataset does not grant those permissions to your dbt identity.

Step 5: Verify the connection

cd doe_family
dbt debug

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

  • Local OAuth credentials missing or using the wrong Google account
  • The dbt identity lacks access to the source or development dataset
  • Wrong project ID, dataset, or location

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 personal Google OAuth without a dbt Cloud Enterprise connection Local

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 Connection settings and authentication method for local dbt
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.