Install the dbt VS Code extension Preview

The dbt extension — available for VS Code, Cursor, and Windsurf — uses the dbt Fusion Engine to make dbt development smoother and more efficient.

note

This is the only official dbt Labs VS Code extension. Other extensions can work alongside the dbt VS Code extension, but they aren’t tested or supported by dbt Labs. Read the Fusion Diaries for the latest updates.

Prerequisites

Before installing, make sure to review the Limitations page as some features don't support Fusion just yet.

To use the extension, you must meet the following prerequisites:

Prerequisite	Details
dbt Fusion Engine	The dbt VS Code extension requires the dbt Fusion Engine binary (a small executable program). The extension will prompt you to install it, or you can install it manually at any time. Register your email within 14 days of installing the dbt extension. Free for up to 15 users.
Project files	- You need a profiles.yml configuration file. ⁃ Existing dbt platform users need to download a dbt_cloud.yml file as well as a profiles.yml file configured in their dbt project. ⁃ Having a dbt platform user account isn't the same as having a dbt platform project — you don't need a dbt platform project to use the extension.
Editor	VS Code, Cursor, or Windsurf code editor.
Operating systems	macOS, Windows, or Linux-based computer.
Configure your local setup (Optional)	Configure the extension to mirror your dbt environment locally and set any environment variables locally to use the VS Code extension features.
Run dbt-autofix (Optional)	Run dbt-autofix to fix any errors and deprecations in your dbt project.

Install the extension

To install the dbt VS Code extension, follow these steps in your editor of choice:

1. Navigate to the Extensions tab of your editor and search for dbt. Locate the extension from the publisher dbtLabsInc or dbt Labs Inc. Click Install.
   Search for the extension
2. Open a dbt project in your VS Code environment if you haven't already. Make sure it is added to your current workspace. If you see a dbt Extension label in your editor's status bar, then the extension has installed successfully. You can hover over this dbt Extension label to see diagnostic information about the extension.
   If you see the 'dbt Extension` label, the extension is activated
3. Once the dbt extension is activated, it will automatically begin downloading the correct dbt Language Server (LSP) for your operating system.
   The dbt Language Server will be installed automatically
4. If the dbt Fusion engine is not already installed on your machine, the extension will prompt you to download and install it. Follow the steps shown in the notification to complete the installation or install it manually from the command line.
   Follow the prompt to install the dbt Fusion engine
5. Run the VS Code extension upgrade tool to ensure your dbt project is Fusion ready and help you fix any errors and deprecations.
6. (Optional) If you're new to the extension or VS Code/Cursor, you can set your local environment to mirror your dbt platform environment and set any environment variables locally to use the VS Code extension features.

You're all set up with the dbt extension! The next steps are:

• Follow the getting started section to begin the terminal onboarding workflow and configure your set up. If you encounter any parsing errors, you can also run thedbt-autofix tool to resolve them.
• Install the dbt Fusion engine from the command line, if you haven't already.
• Register the extension with your email address or dbt platform account to continue using it beyond the trial period.
• Review the limitations and unsupported features if you haven't already.

Install Fusion manually

If you already have the dbt Fusion Engine installed, you can skip this step. If you don't have it installed, you can follow these steps to install it:

1. Open a new command-line window and run the following command to install the dbt Fusion Engine:

   macOS & Linux

   Run the following command in the terminal:

   curl -fsSL https://public.cdn.getdbt.com/fs/install/install.sh | sh -s -- --update

   To use dbtf immediately after installation, reload your shell so that the new $PATH is recognized:

   exec $SHELL

   Or, close and reopen your Terminal window. This will load the updated environment settings into the new session.

   Windows (PowerShell)

   Run the following command in PowerShell:

   irm https://public.cdn.getdbt.com/fs/install/install.ps1 | iex

   To use dbtf immediately after installation, reload your shell so that the new Path is recognized:

   Start-Process powershell

   Or, close and reopen PowerShell. This will load the updated environment settings into the new session.

2. Run the following command to verify you've installed Fusion:

   dbtf --version

   You can use dbt or its Fusion alias dbtf (handy if you already have another dbt CLI installed). Default install path:

   • macOS/Linux: $HOME/.local/bin/dbt
   • Windows: C:\Users\<username>\.local\bin\dbt.exe

   The installer adds this path automatically, but you may need to reload your shell for the dbtf command to work.

3. Follow the getting started guide to get started with the extension. You can get started by either:
   • Running dbtf init to use terminal onboarding,
   • Running Run dbt: Register dbt extension in the command palette,
   • Using the Get started button in the extension menu.

Getting started

Once the dbt Fusion Engine and dbt VS Code extension have been installed in your environment, the dbt logo will appear on the sidebar. From here, you can access workflows to help you get started, offers information about the extension and your dbt project, and provides helpful links to guide you. For more information, see the the dbt extension menu documentation.

You can get started with the extension a couple of ways:

• Running dbtf init to use the terminal onboarding,
• Opening Run dbt: Register dbt extension in the command palette,
• Using the Get started button in the extension menu.

The following steps explain how to get started using the Get started button in the extension menu:

1. From the sidebar menu, click the dbt logo to open the menu and expand the Get started section.
2. Click the dbt Walkthrough status bar to view the welcome screen.
   dbt VS Code extension welcome screen.
3. Click through the items to get started with the extension:
   • Open your dbt project: Launches file explorer so you can select the dbt project you want to open with Fusion.
   • Check Fusion compatibility: Runs the Fusion upgrade workflows to bring your project up-to-date. If you encounter any parsing errors, you can also run thedbt-autofix tool to resolve them.
   • Explore features: Opens the documentation so you can learn more about all the extension has to offer.
   • Register: Launches the registration workflow so you can continue to use the extension beyond the trial period.

Upgrade to Fusion

note

If you are already running the dbt Fusion Engine, you must be on version 2.0.0-beta.66 or higher to use the upgrade tool.

The dbt extension provides a built-in upgrade tool to walk you through the process of configuring Fusion and updating your dbt project to support all of its features and fix any deprecated code. To start the process:

1. From the VS Code sidebar menu, click the dbt logo.

2. In the resulting pane, open the Get started section and click the Get started button.

   The dbt extension help pane and upgrade assistant.

You can also manually start this process by opening a CLI window and running:

dbt init --fusion-upgrade

This will start the upgrade tool and guide you through the Fusion upgrade with a series of prompts:

• Do you have an existing dbt platform account?: If you answer Y, you will be given instructions for downloading your dbt platform profile to register the extension. An N answer will skip to the next step.

• Ready to run a dbtf init? (If there is no profiles.yml file present): You will go through the dbt configuration processes, including connecting to your data warehouse.

• Ready to run a dbtf debug? (If there is an existing profiles.yml file): Validates that your project is configured correctly and can connect to your data warehouse.

• Ready to run a dbtf parse?: Your dbt project will be parsed to check for compatibility with Fusion.

  • If any issues are encountered during the parsing, you'll be given the option to run the dbt-autofix tool to resolve the errors. If you opt to not run the tool during the upgrade processes, you can always run it later or manually fix any errors. However, the upgrade tool cannot continue until the errors are resolved.
    AI Agents

    There are cases where dbt-autofix may not resolve all errors and requires manual intervention. For those cases, the dbt-autofix tool provides an AI Agents.md file to enable AI agents to help with migration work after dbt-autofix has completed its part.

• Ready to run a ‘dbtf compile -static-analysis off’? (Only runs once the parse passes): Compiles your project without any static analysis, mimicking dbt Core. This compile only renders Jinja into SQL, so Fusion's advanced SQL comprehension is temporarily disabled.

• Ready to run a ‘dbtf compile’?: Compiles your project with full Fusion static analysis. It checks that your SQL code is valid in the context of your warehouse's tables and columns.

  The message received when you have completed upgrading your project to the dbt Fusion engine.

Once the upgrade is completed, you're ready to dive into all the features that the dbt Fusion Engine has to offer!

Register the extension

Users must complete registration within 14 days of installing the dbt extension. There are two ways to register:

• Don't have a dbt account? — Follow the VS Code “get started” workflow to register and verify your email. For the initial installation, you only need to provide your name and email address to complete the registration. Subsequent installations will require you to complete the entire dbt account registration process to use the extension.
• Returning user or existing dbt platform user? — If you have an existing dbt platform or previously created one in the past (whether expired or active), no need to register! Just log in with the same email to prevent duplicate accounts. If you can't log in or if it's locked, reach out to dbt Support to have it unlocked or reset before logging in.

The VS Code extension is free for organizations for up to 15 users. See the acceptable use policy for more information.

New user registration

If you do not already have a dbt account, you'll need to get registered. This only takes a minute!

1. Click the registration prompt in your editor.
   The extension registration prompt in VS Code.
2. Accept any prompts to open the link in your browser.
3. Fill out the registration form, then click Continue.
   The extension registration page in the browser.
4. You will receive an email with a verification link. Once you click it, your registration is complete!

Accessing your dbt account

Registering to use the dbt extension makes it easy to create a full dbt account. You can follow these steps to finish setting up your account (Note: This is not required to use the dbt extension).

1. Navigate to us1.dbt.com and click Forgot password?.
2. Enter the email address you used for your dbt extension registration and click Continue.
3. Check your email for a verification link and follow the password reset instructions to set a password for your account.

Now that you have activated your dbt developer account, you can access features of the dbt platform. You can also re-download your registration key using the steps outlined in Register with an existing dbt account if you need to set up the dbt extension on a new machine.

Register with an existing dbt account

During the VS Code extension registration workflow it can detect if you already have a dbt platform account or previously created one in the past (no need to create a new one!).

• If you already have a dbt platform account, you will need to use the same account to connect the extension.
• If you've never created a dbt platform account, skip this section and follow the earlier New user registration steps.
• The extension will use the dbt_cloud.yml file from your dbt platform account, which securely stores your dbt platform account credentials for authentication. You can download this file from your dbt platform's Account settings page.

How the registration works

• If a dbt_cloud.yml file already exists in your ~/.dbt/ (macOS/Linux) or C:\Users\[username]\.dbt (Windows) folder, the extension automatically detects it in the registration flow and uses it.
• If you don’t have the file yet, you’ll need to download it from the dbt platform.

Download the dbt_cloud.yml file

Follow these steps to download the dbt_cloud.yml file:

1. Log into dbt platform and click your account name at the bottom left.
   • If you can't login, follow the accessing your dbt account steps.
2. Click Account settings.
3. Under Your profile, click VS Code Extension.
4. In the Set up your credentials section, click Download credentials to download the dbt_cloud.yml file.
5. Download the dbt_cloud.yml file to complete registration.

Download the dbt_cloud.yml file to complete registration.

6. Move the downloaded dbt_cloud.yml file to your dbt directory:
   • macOS/Linux: ~/.dbt/
   • Windows: C:\Users\[username]\.dbt\

For detailed instructions on how to create a .dbt directory and move the file, see this FAQ. 7. Then go back to VS Code and open the command palette (Ctrl + Shift + P (Windows/Linux) or Cmd + Shift + P (macOS)).
8. Run dbt: Register dbt extension to complete registration. 9. If you run into any issues, reach out to support — we're here to help!

Configure environment variables locally

This section is optional. You only need to configure environment variables locally if your dbt project uses environment variables that are already configured in the dbt platform.

If your dbt project uses environment variables, you can configure them to use the extension's features. See the Configure environment variables page for more information.

Troubleshooting

If you run into any issues, check out the troubleshooting section below.

 How to create a .dbt directory in root and move dbt_cloud.yml file

If you've never had a .dbt directory, you should perform the following recommended steps to create one. If you already have a .dbt directory, move the dbt_cloud.yml file into it. Some information about the .dbt directory:

• A .dbt directory is a hidden folder in the root of your filesystem. It's used to store your dbt configuration files. The . prefix is used to create a hidden folder, which means it's not visible in Finder or File Explorer by default.
• To view hidden files and folders, press Command + Shift + G on macOS or Ctrl + Shift + G on Windows. This opens the "Go to Folder" dialog where you can search for the .dbt directory.

Create a .dbt directory

1. Clone your dbt project repository locally.
2. Use the mkdir command followed by the name of the folder you want to create.

• If using macOS, add the ~ prefix to create a .dbt folder in the root of your filesystem:

mkdir ~/.dbt # macOS
mkdir %USERPROFILE%\.dbt # Windows

Move the dbt_cloud.yml file

You can move the dbt_cloud.yml file into the .dbt directory using the mv command or by dragging and dropping the file into the .dbt directory by opening the Downloads folder using the "Go to Folder" dialog and then using drag-and-drop in the UI.

To move the file using the terminal, use the mv/move command. This command moves the dbt_cloud.yml from the Downloads folder to the .dbt folder. If your dbt_cloud.yml file is located elsewhere, adjust the path accordingly.

Mac or Linux

In your command line, use the mv command to move your dbt_cloud.yml file into the .dbt directory. If you've just downloaded the dbt_cloud.yml file and it's in your Downloads folder, the command might look something like this:

mv ~/Downloads/dbt_cloud.yml ~/.dbt/dbt_cloud.yml

Windows

In your command line, use the move command. Assuming your file is in the Downloads folder, the command might look like this:

move %USERPROFILE%\Downloads\dbt_cloud.yml %USERPROFILE%\.dbt\dbt_cloud.yml

 dbt platform configurations

If you're a cloud-based dbt platform user who has the dbt-cloud: config in the dbt_project.yml file and are also using dbt Mesh, you must have the project ID configured:

dbt-cloud:
project-id: 12345 # Required

If you don’t configure this correctly, cross-platform references will not resolve properly, and you will encounter errors executing dbt commands.

 dbt extension not activating

If the dbt extension has activated successfully, you will see the dbt Extension label in the status bar at the bottom left of your editor. You can view diagnostic information about the dbt extension by clicking the dbt Extension button.

If the dbt Extension label is not present, then it is likely that the dbt extension was not installed successfully. If this happens, try uninstalling the extension, restarting your editor, and then reinstalling the extension.

Note: It is possible to "hide" status bar items in VS Code. Double-check if the dbt Extension status bar label is hidden by right-clicking on the status bar in your editor. If you see dbt Extension in the right-click menu, then the extension has installed successfully.

 Missing dbt LSP features

If you receive a no active LSP for this workspace error message or aren't seeing dbt Language Server (LSP) features in your editor (like autocomplete, go-to-definition, or hover text), start by first following the general troubleshooting steps mentioned earlier.

If you've confirmed the dbt extension is installed correctly but don't see LSP features, try the following:

1. Check extension version — Ensure that you're using the latest available version of the dbt extension by:
   • Opening the Extensions page in your editor, or
   • Going to the Output tab and looking for the version number, or
   • Running dbtf --version in the terminal.
2. Reinstall the LSP — If the version is correct, reinstall the LSP:
   1. Open the Command Palette: Command + Shift + P (macOS) or Ctrl + Shift + P (Windows/Linux).
   2. Paste dbt: Reinstall dbt LSP and enter.

This command downloads the LSP and re-activates the extension to resolve the error.

 Unsupported dbt version

If you see an error message indicating that your version of dbt is unsupported, then there is likely a problem with your environment.

Check the dbt Path setting in your VS Code settings. If this path is set, ensure that it is pointing to a valid dbt Fusion Engine executable. If necessary, you can also install the dbt Fusion Engine directly using these instructions: Install the Fusion CLI

 Addressing the 'dbt language server is not running in this workspace' error

To resolve the dbt language server is not running in this workspace error, you need to add your dbt project folder to a workspace:

1. In VS Code, click File in the toolbar then select Add Folder to Workspace.
2. Select the dbt project file you want to add to a workspace.
3. To save your workspace, click File then select Save Workspace As.
4. Navigate to the location you want to save your workspace.

This should resolve the error and open your dbt project by opening the workspace it belongs to. For more information on workspaces, refer to What is a VS Code workspace?.

More information about Fusion

Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations:

• About the dbt Fusion engine
• About the dbt extension
• New concepts in Fusion
• Supported features matrix
• Installing Fusion CLI
• Installing VS Code extension
• Fusion release track
• Quickstart for Fusion
• Upgrade guide
• Fusion licensing

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.