Skip to main content

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.

The dbt VS Code extension is only compatible with the dbt Fusion engine, but not with dbt Core.

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:

PrerequisiteDetails
dbt Fusion engineThe 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.

⁃ You may need to download a dbt_cloud.yml file depending on your registration path.

⁃ You don't need a dbt platform project to use the extension.
EditorVS Code, Cursor, or Windsurf code editor.
Operating systemsmacOS, 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.
Loading table...

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 extensionSearch 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 activatedIf 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 automaticallyThe 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 engineFollow 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 the dbt-autofix tool to resolve them.
  •  Install the dbt Fusion engine from the command line, if you haven't already.

    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:

      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.

    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.

    1. Follow the getting started guide to get started with the extension. You can get started using one of these methods:
      • 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.
  • 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.

Getting started​

Once the dbt Fusion engine and dbt VS Code extension have been installed in your environment, the dbt logo will appear in the sidebar. Click it to open the Get started panel.

The Get started panel is a persistent, always-on setup companion available in both VS Code and Cursor. It continuously monitors your environment and surfaces the single most important next action. As new Fusion releases ship or your project changes, the panel resurfaces relevant steps automatically.

The Get started panel in VS Code showing the four setup steps, with the active step highlighted as an orange CTA button.The Get started panel in VS Code showing the four setup steps, with the active step highlighted as an orange CTA button.

The panel guides you through four setup steps in order, showing only what's relevant to your current state:

  1. Install or update dbt Fusion engine: Detects whether the dbt Fusion engine binary is missing or outdated and installs or updates it with a single click.
  2. Open project: Checks for a dbt_project.yml file in your workspace to confirm a valid dbt project is open before proceeding.
  3. Check Fusion compatibility: Guides you through upgrading your project to Fusion. When you click this step, you can choose between two paths:
    • Start with an agent: Installs the Migrate dbt Core to Fusion agent skill to your editor's skill folder
      • This opens your AI chat (dbt Copilot or Cursor) with a migration prompt pre-filled.
      • A notification will confirm: "We'll install the Migrate dbt Core to Fusion agent skill to the editor's skill folder. Then we'll open your AI chat with a prompt to start the migration."
      • Click Install & open chat to proceed — the chat opens with the prompt already loaded, so you just press enter and the agent handles the migration. No CLI commands needed. Requires Copilot or Cursor.
    • Start manually in CLI: Runs the Fusion upgrade workflow in your terminal. Refer to Upgrade to Fusion for more info.
  4. Register: Confirms you've registered your email to use the extension beyond the 14-day trial period. See Register the extension.

When all four steps are complete, the panel shows a green Extension setup complete button.

The Get started panel showing Extension setup complete with all four steps checked.The Get started panel showing Extension setup complete with all four steps checked.

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 two ways to upgrade your project to Fusion from the Get started panel:

  • Agentic migration — Automatically runs the -to-Fusion migration via dbt Copilot or Cursor without any CLI steps. Select this option in the Check Fusion compatibility step of the Get started panel. Requires Copilot or Cursor.
  • Manual CLI onboarding — Walks you through the upgrade interactively in your terminal. Use this if you prefer the CLI or don't have Copilot or Cursor.

Manual CLI onboarding​

You can manually update your project to Fusion in a couple of ways:

  • Trigger the manual flow from the Get started panel by selecting the Manual CLI onboarding option in the Check Fusion compatibility step.

  • Run the following command in your terminal:

    dbt init --fusion-upgrade

    The dbt extension Get started panel and upgrade assistant.The dbt extension Get started panel and upgrade assistant.

This starts the upgrade tool and guides 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.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​

After downloading the extension and installing the dbt Fusion engine, make sure you’re running the latest version of the dbt VS Code extension and restart VS Code, then register the extension within 14 days of installing (or re-installing) it.

Key points:

  • The extension is free for organizations for up to 15 users (see the acceptable use policy).
  • Registration links your editor to a dbt account so you can keep using the extension beyond the grace period.
  • This does not require a dbt platform project — just a dbt account.
  • If a valid dbt_cloud.yml file exists on your machine, the extension will automatically use it and skip login.
  • If you already have a dbt account (even from years ago), you will be directed into an OAuth sign-in flow.
 Understanding regions

Most users can sign in from the extension's browser registration page for the default US1 region. If that works, you have an account in the default region and don't need to consider other regions.

Use a credential file (dbt_cloud.yml) instead of sign-in when:

  • You can't sign in.
  • Your organization uses a non-default region (eu1, us2, and so on).
  • You prefer file-based credentials.

If you're unsure whether you have a US1 account from the past, try signing in or using Forgot password at us1.dbt.com. If nothing comes up, continue with Register with dbt_cloud.yml.

Choose your registration path​

Your dbt VS Code extension registration path depends on your situation. Select the one that applies to you:

First-time registration​

Use this if you've never created a dbt account before.

  1. Click the registration prompt or open the command palette (Ctrl + Shift + P (Windows/Linux) or Cmd + Shift + P (macOS)) and type: dbt: Register dbt extension.
    The extension registration prompt in VS Code.The extension registration prompt in VS Code.
  2. In the browser registration form, enter your name and email, then click Continue.
  3. Check your inbox for a verification email and click the verification link.
  4. After verification, return to the browser flow to complete sign‑in.
  5. You'll return to the editor and see Registered.
  6. Continue with the Get started onboarding workflow and get your dbt project up and running.

Note: You do not need a dbt platform project to register; this only creates your dbt account.

Existing account sign-in​

Use this if you have an existing dbt account — including older or inactive accounts. dbt automatically detects your account and dbt_cloud.yml file if it exists (no file download needed). Use this to easily work across machines.

  1. Update the VS Code extension to the latest version and restart your editor before beginning the registration process.
  2. Click the registration prompt or open the command palette and type: dbt: Register dbt extension.
  3. In the browser registration form, select Sign in at the bottom of the form.
  4. Enter your email address associated with your dbt account and click Continue. If you don't remember your password, see Recover your login for help.
  5. You'll then have the option to select your existing dbt account. If you don't have a dbt account, you will be prompted to create an account instead with your existing dbt user.
  6. Select the account you want to use and click Continue.
  7. You should see a page confirming your successful registration. Close the tab and go back to your editor to continue the registration.

When you might still need a dbt_cloud.yml:

  • You want a file-based credential for automations.
  • You're on the free Developer plan and your workflow needs a local credential file for defer.
  • Your region requires it (for example, regions like eu1 or us2).

Recover your login​

Choose this path if the registration form tells you your email already exists but you don't remember your password or your account is locked.

To reset your password and sign in through the OAuth flow:

  1. On the sign-in screen, click Forgot password.
  2. Enter the email associated with your dbt account.
  3. Check your inbox and reset your password.
  4. Return to the sign in screen in the browser and complete the sign-in process.
  5. If you've signed in, you will then have the option to select your existing dbt account.
  6. Select the account you want to use and click Continue.
  7. You should see a page confirming your successful registration. Close the tab and go back to your editor to continue the registration.

If you still can't sign in:

Register with dbt_cloud.yml​

Use this if you can't sign in to your dbt account, your org uses a non-default region (eu1, us2), or your workflow requires a credential file.

  1. Log in to dbt platform and open Account settings → VS Code extension.

  2. In the Set up your credentials section, click Download credentials to get dbt_cloud.yml file.

    Download the dbt_cloud.yml file from your dbt platform account.Download the dbt_cloud.yml file from your dbt platform account.

  3. Move the file into your dbt directory:

    • macOS/Linux: ~/.dbt/dbt_cloud.yml
    • Windows: C:\Users\[username]\.dbt\

    For help creating/moving the .dbt directory, see this FAQ.

  4. Return to the VS Code editor, open the command palette and type: dbt: Register dbt extension.

  5. The extension will detect the credential file and you can continue with the registration flow.

Behavior details:

  • If the dbt_cloud.yml file exists, it takes precedence over any login flow and the extension uses it automatically.
  • If the file is missing, you'll be prompted to sign in or add the file.

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.
  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
 I can't see the lineage tab in Cursor

If you're using the dbt VS Code extension in Cursor, the lineage tab works best in Editor mode and doesn't render in Agent mode. If you're in Agent mode and the lineage tab isn't rendering, just switch to Editor mode to view your project's table and column lineage.

 The extension gets stuck in a loading state

If the extension is attempting to activate during startup and locks into a permanent loading state, check that:

  • Your dbt VS Code extension is on the latest version.
  • Your IDE is on the latest version.
  • You have a valid dbt_cloud.yml file configured and in the correct location.

If you're still experiencing issues, try these steps before contacting dbt Support:

  • Delete and download a new copy of your dbt_cloud.yml file.
  • Delete and reinstall the dbt VS Code extension.
 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?.

 Manifest cannot be downloaded from the dbt platform

If the dbt VS Code extension cannot download the manifest from the dbt platform or you get warning: dbt1200: Failed to download manifest using Fusion locally, you are probably having DNS-related issues.

To confirm this, do a DNS lookup for the host Fusion is trying to download from (for example, prodeu2.blob.core.windows.net) by using dig on Linux/Mac or nslookup on Windows.

If this doesn't return an IP address, the likely reason is that your company uses the same cloud provider with private endpoints for cloud resources, and DNS requests for these are forwarded to private DNS zones.

This situation can be remedied by setting up an internet fallback, which will then return a public IP to any cloud storage that does not have a private IP registered with the private DNS zone.

For Azure refer to Fallback to internet for Azure Private DNS zones.

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:

Was this page helpful?

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

0
Loading