# Quickstart for the dbt Fusion engine [Back to guides](../guides.md) dbt Fusion engine dbt platform Quickstart Beginner [Menu ]() ## Introduction important The dbt Fusion engine is currently available for installation in: * [Local command line interface (CLI) tools](../docs/local/install-dbt.md?version=2) [Preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [VS Code and Cursor with the dbt extension](../docs/install-dbt-extension.md) [Preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [dbt platform environments](../docs/dbt-versions/upgrade-dbt-platform-version.md#dbt-fusion-engine) Join the conversation in our Community Slack channel [`#dbt-fusion-engine`](https://getdbt.slack.com/archives/C088YCAB6GH). Read the [Fusion Diaries](https://github.com/dbt-labs/dbt-core/discussions/categories/announcements?discussions_q=is:open+diaries+category:Announcements) for the latest updates. The dbt Fusion engine is a powerful new approach to classic dbt ideas! Completely rebuilt from the ground up in Rust, Fusion lets you compile and run your dbt projects faster than ever — often in seconds. This quickstart guide will get you from zero to running your first dbt project with Fusion + VS Code. By the end, you’ll have: * A working dbt project (`jaffle_shop`) built with the dbt Fusion engine * The dbt VS Code extension installed and connected * The ability to preview, compile, and run dbt commands directly from your IDE ### About the dbt Fusion engine Fusion and the features it provides are available in multiple environments: | Environment | How to use Fusion | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Studio IDE** | Fusion is automatically enabled; just [upgrade your environment(s)](../docs/dbt-versions/upgrade-dbt-platform-version.md#dbt-fusion-engine). | | **Local CLI** | [Install dbt Fusion engine](../docs/local/install-dbt.md?version=2) locally following this guide. | | **VS Code / Cursor IDE** | [Install the dbt extension](../docs/install-dbt-extension.md) to unlock Fusion's interactive power in your editor. | To learn more about which tool is best for you, see the [Fusion availability](../docs/fusion/fusion-availability.md) page. To learn about the dbt Fusion engine and how it works, read more [about the dbt Fusion engine](../docs/fusion/about-fusion.md). ## Prerequisites To take full advantage of this guide, you'll need to meet the following prerequisites: * You should have a basic understanding of [dbt projects](../docs/build/projects.md), [git workflows](../docs/platform/git/git-version-control.md), and [data warehouse requirements](../docs/supported-data-platforms.md). * Make sure you're using a supported adapter and authentication method:  BigQuery[Preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * Service Account / User Token * Native OAuth * External OAuth * [Workload Identity Federation](../docs/platform/manage-access/set-up-bigquery-oauth.md#set-up-bigquery-workload-identity-federation) (Microsoft Entra) * [Required permissions](../docs/local/connect-data-platform/bigquery-setup.md#required-permissions)  Databricks[Preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * Service Account / User Token * Native OAuth  Redshift[Preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * Username / Password * IAM profile  Snowflake * Username / Password * Native OAuth * External OAuth * Key pair using a modern PKCS#8 method * MFA  Apache Spark (CLI only)[Beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * Thrift * Simple Authentication and Security Layer (SASL) PLAIN * No SASL (NOSASL) * Livy * Basic authentication (username and password) * When deployed on Amazon Web Services (AWS): AWS Signature Version 4 * Supports authentication using single sign-on, service accounts, or user tokens  DuckDB (CLI only)[Beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") DuckDB does not require authentication — it runs locally on your machine. *Note that adapter lifecycle may differ between the dbt platform and local development. An adapter can reach GA in the dbt platform before it reaches GA for local use.* * You need a macOS (Terminal), Linux, or Windows (Powershell) machine to run the dbt Fusion engine. * You need to have [Visual Studio Code](https://code.visualstudio.com/) installed. The [Cursor](https://www.cursor.com/en) code editor will also work, but these instructions will focus on VS Code. * You need admin or install privileges on your machine. ### What you’ll learn By following this guide, you will: * Set up a fully functional dbt environment with an operational project * Install and use the dbt Fusion engine + dbt VS Code extension * Run dbt commands from your IDE or terminal * Preview data, view lineage, and write SQL faster with autocomplete, and more! You can learn more through high-quality [dbt Learn courses and workshops](https://learn.getdbt.com/). ## Installation It's easy to think of the dbt Fusion engine and the dbt extension as two different products, but they're a powerful combo that works together to unlock the full potential of dbt. Think of the dbt Fusion engine as exactly that — an engine. The dbt extension and VS Code are the chassis, and together they form a powerful vehicle for transforming your data. info * You can install the dbt Fusion engine and use it standalone with the CLI. * You *cannot* use the dbt extension without Fusion installed. * Use `dbt` as your default command. If you already have another dbt command-line tool installed (such as the dbt CLI or dbt Core), you can use `dbtf` as an unambiguous alias for Fusion. The following are the essential steps from the [dbt Fusion engine](../docs/local/install-dbt.md?version=2) and [extension](../docs/install-dbt-extension.md) installation guides: 1. Run the following commands to install the dbt Fusion engine CLI: ```shell python -m pip install --pre dbt ``` ### Verify the dbt Fusion engine installation 1. After installation, open a new command-line window to confirm that Fusion installed correctly by checking the version. ```bash dbt --version ``` 2. You should see output similar to the following: ```bash dbt 2.0.0-preview.178 ``` ### Install the dbt VS Code extension The dbt VS Code extension is available in the [Visual Studio extension marketplace](https://marketplace.visualstudio.com/items?itemName=dbtLabsInc.dbt). Download it directly from your VS Code editor: 1. Navigate to the **Extensions** tab of VS Code (or Cursor). 2. Search for `dbt` and choose the one from the publisher `dbt Labs, LLC`. [![Search for the extension](/img/docs/extension/extension-marketplace.png?v=2 "Search for the extension")](#)Search for the extension 3. Click **Install**. 4. When the prompt appears, you can register the extension or skip it. Check out the [registration](../docs/sign-in-dbt-extension.md) or [installation](../docs/install-dbt-extension.md) instructions to come back to it later. 5. Confirm you've installed the extension by looking for the **dbt Extension** label in the status bar. If you see it, the extension was installed successfully! [![Verify installation in the status bar.](/img/docs/extension/extension-lsp-download.png?v=2 "Verify installation in the status bar.")](#)Verify installation in the status bar. ## Initialize the Jaffle Shop project Now let's create your first dbt project powered by Fusion! 1. Run `dbt init` in your terminal from the directory where you want to create the project. The `dbt init` command creates an example project and walks you through setting up a connection profile. * If you *do not* have a connection profile that you want to use, start with `dbt init` and use the prompts to configure a profile: * If you already have a connection profile that you want to use, use the `--skip-profile-setup` flag then edit the generated `dbt_project.yml` to replace `profile: jaffle_shop` with `profile: `. ```bash dbt init --skip-profile-setup ``` * If you created new credentials through the interactive prompts, `init` automatically runs `dbt debug` at the end. This ensures the newly created profile establishes a valid connection with the database. 2. Change directories into your newly created project: ```bash cd jaffle_shop ``` 3. Build your dbt project (which includes creating example data): ```bash dbt build ``` #### Viewing metadata in Catalog Run `dbt build --write-catalog` locally to generate docs metadata (`dbt build` alone does not generate docs metadata). To view that metadata in Catalog, run a job in dbt platform so the metadata is uploaded. For details, refer to [Platform behavior](../reference/commands/cmd-docs.md?version=2.0#platform-behavior). This will: * Load example data into your warehouse * Create, build, and test models * Verify your dbt environment is fully operational ## Explore with the dbt VS Code extension The dbt VS Code extension (available for VS Code and Cursor) compiles and builds your project with the dbt Fusion engine, a powerful and blazing fast rebuild of dbt from the ground up. Want to see Fusion in action? Check out the following video to get a sense of how it works: [dbt Fusion + VS Code extension walkthrough](https://app.storylane.io/share/a1rkqx0mbd7a) Now that your project works, open it in VS Code or Cursor and see Fusion in action: 1. Open the **View** menu and click **Command Palette**. Enter **Workspaces: Add Folder to Workspace**. 2. Select your `jaffle_shop` folder. If you don't add the root folder of the dbt project to the workspace, the [dbt language server](https://docs.getdbt.com/blog/dbt-fusion-engine-components#the-dbt-vs-code-extension-and-language-server) (LSP) will not run. The LSP enables features like autocomplete, hover info, and inline error highlights. 3. Click the **dbt logo** in the sidebar to open the **Get started** panel. The panel detects your environment and surfaces the next setup step, including installing the Fusion binary, confirming your project is open, checking Fusion compatibility, and registering. If you haven't already upgraded your project to Fusion, you can choose **Start with an agent** (Copilot or Cursor) or **Start manually in CLI** directly from the panel. For full details, see [Getting started](../docs/install-dbt-extension.md#getting-started). 4. Open a model file to see the definition for the `orders` model. This is the model we'll use in all of the examples below. ```bash models/marts/orders.sql ``` 5. Locate **Lineage** and **Query Results** in the lower panel, and the **dbt icon** in the upper right corner next to your editor groups. If you see all of these, the extension is installed correctly and running! [![The VS Code UI with the extension running.](/img/docs/extension/extension-running.png?v=2 "The VS Code UI with the extension running.")](#)The VS Code UI with the extension running. Now you're ready to see some of these awesome features in action! * [Preview data and code](#preview-data-and-code) * [Navigate your project with lineage tools](#navigate-your-project-with-lineage-tools) * [Use the power of SQL understanding](#use-the-power-of-sql-understanding) * [Speed up common dbt commands](#speed-up-common-dbt-commands) #### Preview data and code Gain valuable insights into your data transformation during each step of your development process. You can quickly access model results and underlying data structures directly from your code. These previews help validate your code step-by-step. 1. Locate the **table icon** for **Preview File** in the upper right corner. Click it to preview results in the **Query Results** tab. [![Preview model query results.](/img/docs/extension/preview-query-results.png?v=2 "Preview model query results.")](#)Preview model query results. 2. Click **Preview CTE** above `orders as (` to preview results in the **Query Results** tab. [![Preview CTE query results.](/img/docs/extension/preview-cte-query-results-3.png?v=2 "Preview CTE query results.")](#)Preview CTE query results. 3. Locate the code icon for **Compile File** in between the dbt and the table icons. Clicking this icon opens a window with the compiled version of the model. [![Compile File icon.](/img/docs/extension/compile-file-icon.png?v=2 "Compile File icon.")](#)Compile File icon. [![Compile File results.](/img/docs/extension/compile-file.png?v=2 "Compile File results.")](#)Compile File results. #### Navigate your project with lineage tools Almost as important as where your data is going is where it's been. The lineage tools in the extension let you visualize the lineage of the resources in your models as well as the column-level lineage. These capabilities deepen your understanding of model relationships and dependencies. 1. Open the **Lineage** tab to visualize the model-level lineage of this model. [![Visualizing model-level lineage.](/img/docs/extension/extension-pane.png?v=2 "Visualizing model-level lineage.")](#)Visualizing model-level lineage. 2. Open the **View** menu, click **Command Palette** and enter `dbt: Show Column Lineage` to visualize the column-level lineage in the **Lineage** tab. [![Show column-level lineage.](/img/docs/extension/show-cll.png?v=2 "Show column-level lineage.")](#)Show column-level lineage. #### Use the power of SQL understanding Code smarter, not harder. The autocomplete and context clues help avoid mistakes and enable you to write fast and accurate SQL. Catch issues before you commit them! 1. To see **Autocomplete** in action, delete `ref('stg_orders')`, and begin typing `ref(stg_` to see the subset of matching model names. Use up and down arrows to select `stg_orders`. [![Autocomplete for a model name.](/img/docs/extension/autocomplete.png?v=2 "Autocomplete for a model name.")](#)Autocomplete for a model name. 2. Hover over any `*` to see the list of column names and data types being selected. [![Hovering over \* to see column names and data types.](/img/docs/extension/hover-star.png?v=2 "Hovering over * to see column names and data types.")](#)Hovering over \* to see column names and data types. #### Speed up common dbt commands Testing, testing... is this mic on? It is and it's ready to execute your commands with blazing fast speeds! When you want to test your code against various dbt commands: 1. The dbt icon in the top right opens a list of extension-specific commands: [![Select a command via the dbt icon.](/img/docs/extension/run-command.png?v=2 "Select a command via the dbt icon.")](#)Select a command via the dbt icon. 2. Opening the **View** menu, clicking the **Command Palette**, and entering `>dbt:` in the command bar shows all the new commands that are available. [![dbt commands in the command bar.](/img/docs/extension/extension-commands-all.png?v=2 "dbt commands in the command bar.")](#)dbt commands in the command bar. Try choosing some of them and see what they do 😎 This is just the start. There is so much more available and so much more coming. Be sure to check out our resources for all the information about the dbt Fusion engine and the dbt VS Code extension! ## 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: * macOS: `mkdir ~/.dbt` * Windows: `mkdir %USERPROFILE%\.dbt` ### 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: ```bash 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: ```bash move %USERPROFILE%\Downloads\dbt_cloud.yml %USERPROFILE%\.dbt\dbt_cloud.yml ```  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](#register-with-dbt_cloudyml). 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: ```yaml 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](../docs/local/install-dbt.md?version=2)  dbt Fusion binary not found at the configured path If the extension reports that the dbt Fusion engine binary can't be found at the configured path (for example, `dbt-fusion binary not found at [path]`), the `dbt.fusionPath` setting is pointing to a location that doesn't contain a valid binary. * Verify that [`dbt.fusionPath`](../docs/configure-dbt-extension.md#dbt-extension-settings) points to a valid Fusion binary. * If you haven't installed Fusion manually, clear the setting and let the extension download and manage it for you. * To install manually, follow [Install the Fusion CLI](../docs/local/install-dbt.md?version=2).  dbt Fusion version is not compatible with this extension If the extension reports that the installed Fusion version isn't compatible with your dbt VS Code extension version, the two are outside the supported range. 1. Run `dbt --version` to check your installed Fusion version. 2. Compare it against the [version compatibility matrix](../docs/dbt-versions/fusion-version-compatibility.md#compatibility-matrix) for your extension version. 3. Update Fusion or the extension so both fall within the supported range. Use the **Download compatible version** action in the notification if it appears.  dbt Fusion crashes on startup If the extension reports that Fusion crashed on startup, confirm the binary runs on its own: 1. Run `dbt --version` in your terminal. If this fails, reinstall Fusion using [Install the Fusion CLI](../docs/local/install-dbt.md?version=2). 2. Use the **Show Logs** action in the notification (or open the **Output** tab) to review the startup error.  A known-bad dbt Fusion version is installed If the extension warns that your installed Fusion version has a known regression, dbt Labs has flagged that release as [known-bad](../docs/dbt-versions/fusion-version-compatibility.md#known-bad-releases). Update to the version named in the notification. For standalone installations: ```shell dbt system update ``` The warning persists across restarts until you update. If you work in an air-gapped environment, refer to [known-bad releases](../docs/dbt-versions/fusion-version-compatibility.md#known-bad-releases) for how to distribute the manifest locally.  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?](https://code.visualstudio.com/docs/editing/workspaces/workspaces).  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](https://learn.microsoft.com/en-us/azure/dns/private-dns-fallback). ## More information about Fusion * [About the dbt extension](../docs/about-dbt-extension.md) * [Supported features matrix](../docs/fusion/supported-features.md) * [Install dbt](../docs/local/install-dbt.md) * [Quickstart for Fusion](./fusion.md?step=1) * [Upgrade guide](../docs/dbt-versions/core-upgrade/upgrading-to-v2.md) * [Fusion license agreement](https://www.getdbt.com/dbt-fusion-engine-license-agreement) ## Was this page helpful? YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy)[Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply.