Install the dbt VS Code extension Preview

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

The dbt VS Code extension is compatible with the dbt Fusion engine. It isn't compatible 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, review the limitations page because some features don't support Fusion yet.

To use the extension, you need the following:

Prerequisite	Details
dbt Fusion engine	The dbt VS Code extension requires the dbt Fusion engine binary. The extension prompts you to install it, or you can install it manually.
Project files	You need a profiles.yml file. You may also need a dbt_cloud.yml file for some dbt platform features or credential-based workflows. You don't need a dbt platform project to use the extension.
Editor	VS Code, Cursor, or Windsurf.
Operating system	macOS, Windows, or Linux.
Local configuration (optional)	Configure the extension to mirror your dbt environment locally and set any environment variables required by your project.
Project migration support (optional)	Use the Migrate dbt Core to Fusion agent skill or run dbt-autofix to help resolve errors and deprecations before using Fusion.

Install the extension

1. In your editor, open the Extensions tab and search for dbt.

2. Locate the extension from the publisher dbtLabsInc or dbt Labs Inc, then click Install.

   Search for the extension

3. Open a dbt project in your editor. Make sure the project is added to your current workspace.

4. Confirm that the extension is active by checking for the dbt Extension label in the status bar. Hover over the label to view diagnostic information.

   If you see the 'dbt Extension' label, the extension is activated

5. After the extension activates, it automatically downloads the correct dbt Language Server (LSP) for your operating system.

   The dbt Language Server will be installed automatically

6. If the dbt Fusion engine isn't installed, the extension prompts you to download and install it. Follow the notification steps, or install it manually from the command line.

   Follow the prompt to install the dbt Fusion engine

7. Run the VS Code extension upgrade tool to check whether your project is ready for Fusion and fix any errors or deprecations.

8. Optional: Configure your local environment to mirror your dbt platform environment and set environment variables required by your project.

You're ready to use the dbt extension. Next, you can:

• Follow the getting started workflow to finish setup.
• Upgrade your project to Fusion if you're migrating from dbt Core.
• Sign in or register for a dbt platform account to keep using advanced features after the 14-day trial.
• Review the limitations and unsupported features.

 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, choose your preferred installation method:

macOS & Linux (CDN)

Run the following command in the terminal:

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

To use dbt 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 (CDN)

Run the following command in PowerShell:

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

To use dbt 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.

Homebrew (macOS)

If you have Homebrew installed, run:

brew install dbt

To upgrade to a newer version:

brew upgrade dbt

winget (Windows)

If you have winget installed, run:

winget install --id dbtLabs.dbt --exact

To upgrade to a specific version:

winget install --id dbtLabs.dbt --exact --version <version>

pip

You can install Fusion using pip. We recommend installing into a Python virtual environment to avoid dependency conflicts.

Set up a virtual environment (recommended)

macOS & Linux

python3 -m venv .venv
source .venv/bin/activate

Windows

py -m venv .venv
.venv\Scripts\activate

Install dbt

Run the following commands to install the preview version and update to the latest.

pip install dbt==2.0.0rc178
dbt system update

The pip install dbt command installs the latest stable release. dbt system update then pulls the latest dbt Fusion engine binary.

Deactivate the virtual environment

When you're done, deactivate the environment:

deactivate

Run the following command to verify your installation:

dbt --version

You can use dbt or its Fusion alias dbtf (handy if you already have the Core or platform 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.

After installation, follow the getting started workflow. You can get started by:

• Running dbt init --fusion-upgrade to start terminal onboarding.
• Running dbt: Register dbt extension from the command palette.
• Selecting Get started from the extension menu.

Getting started

After the dbt Fusion engine and dbt VS Code extension are installed, the dbt logo appears in the sidebar. Click it to open the Get started panel.

The Get started panel is a persistent setup companion available in VS Code and Cursor. It monitors your environment and shows the most important next action. As new Fusion releases ship or your project changes, the panel resurfaces relevant steps automatically. For more details refer to Upgrade to Fusion.

The Get started panel in VS Code showing the setup steps, with the active step highlighted.

The panel guides you through:

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. You can choose between an agentic migration or manual CLI onboarding — refer to Upgrade to Fusion.
4. Register: Confirms you've registered your email to use the extension beyond the 14-day trial period — refer to Sign in or register.

When all setup 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.

Next steps

Once you've installed the dbt VS Code extension, go to the next pages to get started:

1. Review the Upgrade to Fusion page to ensure your dbt project is using the dbt Fusion engine.
2. Sign in or register for a dbt platform account to keep using advanced features after the 14-day trial.
3. Review the limitations and unsupported features.

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.