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

This section explains how to prepare your local environment to mirror your dbt project environment. If you already have your local environment set up, you don't need to do anything here.

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.

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	When to use
Shell profile	Terminal	✅ Permanent	Variables remain active globally and available across terminal sessions.
VS Code/Cursor settings	Extension menus + LSP	✅ Per VS Code/Cursor profile	Editor-only workflows using the extension menu actions.
One terminal session	Current terminal only	❌ Temporary	One off quick testing.

tip

If you want to use both the VS Code extension menus and terminal to run dbt commands, define your variables in both the shell profile so they remain active globally and in VS Code/Cursor 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.

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. A file will open up and you can 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.
4. Start a new shell session by closing and reopening the terminal or running source ~/.zshrc or source ~/.bashrc in the terminal.
5. 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

To use the dbt extension menu actions/buttons, you can configure environment variables directly in the User Settings interface or in any .env file at the root level.

• 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 VS Code/Cursor:

Open User 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 in the dropdown menu.
3. Open the VS Code user settings page.
4. Search for dbt.environmentVariables.
5. In the dbt:Environment Variables section, add your item and value for the environment variables.
6. Click Ok to save the changes.
7. Reload the VS Code extension to apply the changes.
8. Verify the changes by running a dbt command and checking the output.

Open .env file

1. In your dbt project, create a .env file at the root level (same level as your dbt_project.yml file).
2. Add your environment variables to the file. For example:

   DBT_ENV_VAR1=my_value
   DBT_ENV_VAR2=another_value
3. Save the file.
4. Reload the VS Code extension to apply the changes.
5. Verify the changes by running a dbt command using the extension menu button on the top right corner 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.

Next steps

Now that you've configured your local environment, you can start using the dbt extension to streamline your dbt development workflows. Check out the following resources to get started:

• About the dbt extension
• dbt extension features
• Register the extension

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.