In this walkthrough, username and my_dbt_project_name are used as placeholder values. They should be replaced with the actual username and project name before running the steps.

Most steps should be run from the project root directory (/home/username/projects/my_dbt_project_name), except dbt init, which must be run from the parent directory.

STEP 1: Requirements check (WSL/Linux)

Before starting, the following should be verified as installed on your system:

python3 --version  # Python 3 should be 3.8+ (venv + dbt need it)
pip --version      # pip should be available (install Python packages)
git --version      # Git should be available (version control)
gcloud --version   # Google Cloud SDK should be available (BigQuery auth)
curl --version     # curl should be available (download files via URL, used for the Google repo key)

Note: dbt will be installed in the project venv after dbt init. A temporary global install is used only for initialization.

If any of the checks above are missing, they can be installed with:

# 0) Refresh package list (recommended)
sudo apt update

# 1) Core tools: Python + venv + pip + Git
sudo apt install -y python3 python3-venv python3-pip
sudo apt install -y git

# 2) Prepare apt for Google's repo (HTTPS + GPG)
sudo apt install -y apt-transport-https ca-certificates gnupg

# 3) Add Google's signing key
curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg

# 4) Add Google's Cloud SDK repo to apt
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
  | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list

# 5) Refresh package list after adding the new repo
sudo apt update

# 6) Install the gcloud CLI
sudo apt install -y google-cloud-cli

The official install guide can also be followed for the latest steps: https://cloud.google.com/sdk/docs/install#linux

STEP 2: Install dbt CLI globally (for dbt init)

Before dbt init is run, a global dbt CLI must exist so the command is available. The project folder is created by dbt init, so a temporary global install is used only for initialization. After init, the project venv dbt should be used for all dbt commands.

This isolated method is the recommended practice because a direct pip install dbt-bigquery can later cause version or dependency conflicts when multiple projects need different dbt versions. A global pip install dbt-bigquery also clutters the system Python environment. pipx avoids that by installing dbt in its own isolated environment while still providing a global dbt command.

# Install pipx (isolated Python apps)
sudo apt install -y pipx  # install pipx for isolated CLI tools
pipx ensurepath  # add ~/.local/bin to PATH (created by pipx or pip --user, stores user-level CLI commands)
source ~/.bashrc  # Reload bash config so the new PATH is applied now.
# If the PATH is still not updated, open a new terminal (or restart VS Code)

# Install dbt (BigQuery adapter includes dbt-core)
pipx install dbt-bigquery

# Verify
pipx run dbt --version

STEP 3: Initialize dbt project (repo root)

dbt init should be run from the parent directory, using the repo name as the dbt project name. The target folder should not exist yet, or it should be empty, before running dbt init.

cd /home/username/projects # change to parent directory
dbt init my_dbt_project_name

Interactive prompts will be shown:

  1. Project name: my_dbt_project_name
  2. Which database: bigquery
  3. Authentication method: oauth
  4. Project ID: gcp-project-id
  5. Dataset: gcp-dataset-name
  6. Threads: 1
  7. Location: EU

After dbt init completes:

  • Project folder: /home/username/projects/my_dbt_project_name/
  • Profile file is created: ~/.dbt/profiles.yml (in your WSL HOME, not project!) To view: code ~/.dbt/profiles.yml
  • Core structure is created:
    • dbt_project.yml (project config)
    • models/ (SQL models go here)
    • README.md
    • .gitignore (dbt-specific, auto-created if missing)

STEP 4: Update .gitignore

The .gitignore file may already exist after dbt init. The rules below should be appended so the venv and dbt outputs are not tracked.

cd /home/username/projects/my_dbt_project_name
cat >> .gitignore << 'GITIGNORE'

# --- Python virtual environments (avoid huge venv files) ---
.venv/          # default venv folder
venv/           # alternate venv folder
ENV/            # alternate venv folder
env/            # alternate venv folder

# --- Python bytecode/build artifacts (auto-generated by Python) ---
__pycache__/    # Python bytecode cache
*.py[cod]       # compiled Python files
*$py.class      # legacy Python bytecode

# --- dbt outputs & dependencies (auto-generated by dbt) ---
target/         # dbt build artifacts
dbt_packages/   # dbt package installs
logs/           # dbt logs
dbt_modules/    # legacy dbt deps dir
*.log           # generic log files

# --- IDE/editor files (local machine settings) ---
.vscode/        # VS Code settings
.idea/          # JetBrains settings

# --- OS files (local machine metadata) ---
.DS_Store       # macOS metadata
Thumbs.db       # Windows thumbnails

# --- Environment variables (secrets) ---
.env            # local env vars
.env.local      # local env vars
GITIGNORE

STEP 5: Initialize Git repository (optional)

Initialize the local Git repository first. If the GitHub repository does not exist yet, create it before the first push. This step does not change the existing .gitignore file.

cd /home/username/projects/my_dbt_project_name
git init
git branch -M main  # optional: rename default branch to main
git remote add origin <repo-url>  # set GitHub repo URL for push/pull

STEP 6: Create virtual environment

A .venv/ folder is created in the project root.

cd /home/username/projects/my_dbt_project_name
python3 -m venv .venv

STEP 7: Activate virtual environment

Activation of venv does NOT mean you’re “inside .venv folder”. From this point, the terminal will use Python and packages from .venv. Your physical location (pwd) stays the same!

source .venv/bin/activate

Venv activation should be confirmed by the “(.venv)” prefix in terminal.

STEP 8: Install dbt in the venv

Venv should be active.

  • dbt-core: Core functionality (SQL compilation, model execution, testing)
  • dbt-bigquery: Adapter for BigQuery (connection, BigQuery-specific SQL)

The adapter alone can be installed, which automatically includes dbt-core. The following command explicitly installs both for clarity:

pip install dbt-core dbt-bigquery

Installation should be verified:

dbt --version

STEP 9: Save installed packages

All installed packages in the venv are exported to requirements.txt. This file is created in the project root. In this workflow, only dbt-core and dbt-bigquery are installed directly; the rest of the entries are their dependencies.

pip freeze > requirements.txt
# cat requirements.txt # Optional: show contents

STEP 10: Authenticate with Google Cloud

This step is required before dbt debug. OAuth authentication for BigQuery access is required:

gcloud auth application-default login

The following is done:

  1. A browser is opened (Windows browser from WSL)
  2. Login is completed with your Google account
  3. Credentials are saved to ~/.config/gcloud/application_default_credentials.json
  4. These credentials are used automatically by dbt

This command creates the credentials used by dbt to access BigQuery:

  • OAuth2 tokens (access token + refresh token)
  • Credential file saved at: ~/.config/gcloud/application_default_credentials.json
  • This file is used as the access key for BigQuery
  • Access token is set to expire (~1 hour), but refresh token is auto-renewed

Important: This credential file lives outside the project (~/.config/gcloud/...). It should not be copied into the repo or committed to Git. To revoke/delete: run gcloud auth application-default revoke.

STEP 11: Test dbt configuration

dbt init should be completed, gcloud auth should be completed, and venv should be active.

cd /home/username/projects/my_dbt_project_name
dbt debug

Expected output: “All checks passed!”. If errors occur, ~/.dbt/profiles.yml should be checked.

STEP 12: Git commit

Changes should be staged and committed from the project root:

cd /home/username/projects/my_dbt_project_name
git add .  # stage all changes
git commit -m "Initial dbt project setup"
git push -u origin main