Configure the dbt VS Code extension

This page explains how to configure local setup for the dbt VS Code extension and configure environment variables, if your project uses them. The steps differ slightly depending on whether you use dbt platform or dbt Core.

• dbt platform — You’ll mirror your dbt platform environment locally to unlock Fusion-powered features like Mesh, deferral, and so on.
• dbt Core — You’ll confirm that your existing local setup and environment variables work seamlessly with the dbt Fusion Engine and VS Code extension.

Prepare your local environment

If you're a dbt platform user new to the extension or VS Code/Cursor, you'll need to set up your local environment to mirror your dbt platform environment and follow these steps.

If you already have your local environment set up, skip to the next section.

1. Clone your dbt project locally by cloning your dbt platform repo (from your Git provider).
2. Ensure you have a dbt profiles.yml file. This file defines your data warehouse connection. If you don't have one, you'll go through the dbt configuration processes to set it up.
3. Once you've set this up or checked it, validate it by running dbt debug.
4. Add a dbt_cloud.yml file by going to the dbt platform project:
   • Your profile -> VS Code Extension -> Download credentials.
   • Download the dbt_cloud.yml file with your Personal access Token (PAT) included. This then connects the extension to dbt platform and enables platform features such as Mesh and deferral.
   • Check the project_id in your dbt_project.yml file matching the project you're working on.
5. Confirm connection from your workstation. Your local computer connects directly to your data warehouse and Git.
   • dbt platform users: Ensure your laptop/VPN is allowed; dbt platform IPs no longer apply. Check with your admin if you have any issues.
   • dbt Core users: This has likely already been configured.
6. (Optional) If your project uses environment variables, find your environment variables and set them in VS Code or Cursor.
   • dbt platform users: Copy any environment variables from Deploy → Environments → Environment variables tab in dbt platform. Masked secrets will appear hidden, speak with your admin to get those values.
   • dbt Core users: You'll most likely have defined your own env_var() references locally if your project uses them.

Set environment variables locally

The extension and CLI uses environment variables for authentication and configuration. The following table shows the different options and when to use them:

Location	Affects	Session state	Use when
Shell profile (~/.zshrc, ~/.bashrc, PowerShell profile)	Terminal	✅ Permanent	Variables remain active globally and available across terminal sessions.
VS Code/Cursor settings (dbt.environmentVariables or .env file at the root level)	Extension menus + LSP	✅ Per VS Code/Cursor profile	Editor-only workflows using the extension menu actions.
One terminal session (export / set)	Current terminal only	❌ Temporary	Quick testing.

If you want to use both the VS Code extension menus and terminal commands, define your variables in both the shell profile so they remain active globally and in VS Code settings if you use extension menu actions.

Configure at the OS / shell level

Define variables once at the OS or shell level to ensure they're available to all terminals. Even if you close a terminal window, the variables will remain available to you.

Follow these steps to configure environment variables at the OS or shell level:

Mac / Linux

1. Open your shell configuration file in a text editor using the following commands: (If the file does not exist, create it using a text editor using vi ~/.zshrc or vi ~/.bashrc).

   open -e ~/.zshrc ## for zsh (macOS)
   nano ~/.bashrc ## for bash (Linux or older macOS)
2. Add your environment variables to the file. For example:
   • For zsh (macOS):

         ## ~/.zshrc 
         export DBT_ENV_VAR1="my_value"
         export DBT_ENV_VAR2="another_value"
   • For bash (Linux or older macOS):

         ## ~/.bashrc or ~/.bash_profile
         export DBT_ENV_VAR1="my_value"
         export DBT_ENV_VAR2="another_value"
3. Save the file and start a new shell session by closing and reopening the terminal or running source ~/.zshrc or source ~/.bashrc in the terminal.
4. Then verify the variables by running echo $DBT_ENV_VAR1 and echo $DBT_ENV_VAR2 in the terminal.
   

If you see the value printed back in the terminal, you're all set! These variables will now be available:

• In all future terminal sessions
• For all dbt commands run in the terminal

Windows Cmd

There are two main ways to create persistent environment variables on Windows: through PowerShell or the Environment Variables UI.

The following steps will explain how to configure environment variables using PowerShell.

PowerShell

1. Run the following commands in PowerShell:

  [Environment]::SetEnvironmentVariable("DBT_ENV_VAR1","my_value","User")
  [Environment]::SetEnvironmentVariable("DBT_ENV_VAR2","another_value","User")

1. This saves the variables permanently for your user account. (To make them available system-wide for all users, replace "User" with "Machine" (requires admin rights)).
2. Then, restart VS Code or select Developer: Reload Window for changes to take effect.
3. Verify the changes by running echo $DBT_ENV_VAR1 and echo $DBT_ENV_VAR2 in the terminal.

GUI (Environment Variables)

1. Press Start → search for Environment Variables → open Edit the system environment variables.
2. Click Environment Variables….
3. Under User variables, click New….
4. Add the variables and values. For example:
   • Variable name: DBT_ENV_VAR1
   • Variable value: my_value
5. Repeat for any others, then click OK.
6. Restart VS Code or Cursor.
7. Verify the changes by running echo $DBT_ENV_VAR1 and echo $DBT_ENV_VAR2 in the terminal.

Configure in the VS Code extension settings

You can configure environment variables directly in the User Settings interface or in the JSON file.
Something to keep in mind:

• Configuring in the User Settings works with the dbt extension buttons and menus (for LSP, "Show build menu," and so on).
• Not inherited by the VS Code terminal or external shells.
• Running a dbt command in the terminal won't fetch or use these variables.

To configure environment variables in the VS Code extension settings:

1. Open the Command Palette (Cmd + Shift + P for Mac, Ctrl + Shift + P for Windows/Linux).
2. Then select either Preferences: Open User Settings or Preferences: Open Settings (JSON) in the dropdown menu.

Open User Settings

1. Open the VS Code user settings page.
2. Search for dbt.environmentVariables.
3. In the dbt:Environment Variables section, add your item and value for the environment variables.
4. Click Ok to save the changes.
5. Reload the VS Code extension to apply the changes.
6. Verify the changes by running a dbt command and checking the output.

Open Settings (JSON)

1. Open the JSON file.
2. Add your environment variables as a JSON object to the .vscode/settings.json file in your dbt project. For example:

   {
   "dbt.environmentVariables": {
     "DBT_ENV_VAR1": "test_santi_value" // replace DBT_ENV_VAR1 and test_santi_value with your own variable and value
    }
   }
3. Save the changes.
4. Reload the VS Code extension to apply the changes.
5. Verify the changes by running a dbt command and checking the output.

Configure in the terminal session

Configure environment variables in the terminal session using the export command. Something to keep in mind:

• Doing so will make variables visible to commands that run in that terminal session only.
• It lasts only for the current session and opening a new terminal will lose the values.
• The built-in dbt VS Code extension buttons and menus will not pick these up.

To configure environment variables in the terminal session:

1. Run the following command in the terminal, replacing DBT_ENV_VAR1 and test1 with your own variable and value.

   Mac / Linux

   export DBT_ENV_VAR1=test1

   Windows Cmd

   Refer to Microsoft's documentation for more information on the set command.

   set DBT_ENV_VAR1=test1 
   

   Windows PowerShell

   Refer to Microsoft's documentation for more information on the $env: syntax.

   $env:DBT_ENV_VAR1 = "test1"

2. Verify the changes by running a dbt command and checking the output.

Example: Shell-level setup (macOS zsh)

Was this page helpful?

Privacy policyCreate a GitHub issue

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.