---
title: "Upgrade to Fusion part 1: Preparing to upgrade"
source: dbt Core Documentation
source_url: https://github.com/dbt-labs/docs.getdbt.com
licence: Apache-2.0
domain: data-and-analysis
subdomain: dbt-docs
date_added: 2026-04-25
---

import FusionAdapters from '/snippets/_fusion-dwh.md';

## Introduction

import FusionPreview from '/snippets/_fusion-private-preview.md';

<FusionPreview />

The <Constant name="fusion_engine" /> represents the next evolution of data transformation. dbt has been rebuilt from the ground up but at its most basic, <Constant name="fusion" /> is a new version, and like any new version you should take steps to prepare to upgrade. This guide will take you through those preparations. 

If <Constant name="fusion" /> is brand new to you, take a look at our [comprehensive documentation](/docs/fusion) on what it is, how it behaves, and what's different from <Constant name="core" /> before getting started with this guide. Once you're caught up, it's time to begin preparing your projects for the speed and power that <Constant name="fusion" /> has to offer.

## Prerequisites

This guide will cover the preparations for upgrading to the <Constant name="fusion_engine" /> and is intended for customers already using the <Constant name="dbt_platform" /> with a version of <Constant name="core" />. If you're brand new to dbt, check out our [quickstart guides](/guides).

To follow the steps in this guide, you must meet the following prerequisites:

- You're using a <Constant name="dbt_platform" /> account on any tier.
- You have a developer license.
- You have [proper permissions](/docs/cloud/manage-access/enterprise-permissions) to edit projects.
- Your project is using a <Constant name="fusion" /> supported adapter:
    <FusionAdapters/>

:::tip Upgrading your first project

Start with smaller, newer, or more familiar projects first. This makes it easier to identify and troubleshoot any issues before upgrading larger, more complex projects.

:::

## Enable Fusion readiness features

The <Constant name="fusion" /> readiness panel in the <Constant name="dbt_platform" /> and shows each project's eligibility status and blockers, is being rolled out in phases. If it hasn't been automatically enabled for your account yet, an [account admin](/docs/cloud/manage-access/enterprise-permissions#account-admin) can manually enable it. This lets admins and developers see which projects and jobs are eligible for <Constant name="fusion" />, identify blockers, and initiate the upgrade once preparation is complete.

### Step 1: Enable the readiness toggle

This step requires account admin access in <Constant name="dbt_platform" />:

1. Click your account name in the left sidebar and select **Account settings**.
2. Navigate to the **Account** screen and click **Edit**.
3. Scroll to the **Settings** section and select the checkbox next to **Enable Fusion readiness & upgrade features**.
4. Click **Save**.

Once enabled:
- All admins and developers can see each project's <Constant name="fusion" /> readiness status, including which jobs are eligible or ineligible for <Constant name="fusion" /> and why.
- Admins can initiate the <Constant name="fusion" /> upgrade from development environments, environment settings, and job settings (subject to existing permissions).

### Step 2: Restrict upgrade access (optional)

By default, any user who can see the upgrade assistant can use it to initiate an upgrade. To limit upgrade execution to designated users, you can enable an additional access control toggle.

:::note Enterprise tier accounts only

The **Enable restricted Fusion upgrade permissions** toggle is only available to Enterprise/Enterprise+ accounts that have been granted this entitlement. Contact your account manager if you need this capability.

:::

1. In the same **Account** settings screen, select the checkbox next to **Enable restricted Fusion upgrade permissions**.
2. Click **Save**.

When enabled, only users assigned the [`Fusion admin`](/docs/cloud/manage-access/enterprise-permissions#fusion-admin) permission set (scoped to specific projects) can execute the upgrade. For instructions on assigning this permission, refer to [Assign upgrade access](/guides/upgrade-to-fusion?step=3#assign-upgrade-access-optional) in Part 2 of this guide.

### The Fusion readiness panel

With the readiness experience enabled, you can monitor your project's eligibility as you work through the preparation steps below. The panel shows which jobs are eligible or ineligible for <Constant name="fusion" /> and why.

<Lightbox src="/img/fusion/fusion-readiness.png" width="60%" title="The Fusion readiness checklist"/>

Common ineligibility reasons include:
- Environment(s) not on the **Latest** [release track](/docs/dbt-versions/cloud-release-tracks#which-release-tracks-are-available]
- Not using a [supported data platform](/docs/fusion/supported-features?version=2.0#requirements)
- Project doesn't have at least one successful job run
- Jobs that haven't run in the last 7 days or have recent failures

As you complete the steps in this guide, check the readiness panel to see your eligibility improve.

## Upgrade to the latest dbt Core version

Before upgrading to <Constant name="fusion" />, you need to move your environments to the **Latest** [<Constant name="core" /> release track](/docs/dbt-versions/cloud-release-tracks). The **Latest** track includes all the features and tooling to help you prepare for <Constant name="fusion" />. It ensures the smoothest upgrade experience by validating that your project doesn't rely on deprecated behaviors.

:::tip Test before you deploy

Always test version upgrades in development first. Use the [Override dbt version](#step-1-test-in-development-using-override) feature to safely try the **Latest** release track without affecting your team or production runs.

:::

### Step 1: Test in development (using override)

Test the **Latest** release track for your individual account without changing the environment for your entire team:

1. Click your account name in the left sidebar and select **Account settings**.
2. Select **Credentials** from the sidebar and choose your project.
3. In the side panel, click **Edit** and scroll to **User development settings**.
4. Select **Latest** from the **dbt version** dropdown and click **Save**.

<Lightbox src="/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/choosing-dbt-version/example-override-version.png" width="60%" title="Override dbt version in your account settings"/>

5. Launch the <Constant name="studio_ide" /> or <Constant name="platform_cli" /> and test your normal development workflows.
6. Verify the override is active by running any dbt command and checking the **System Logs**. The first line should show `Running with dbt=` and your selected version. If the version number is `v1.11` or higher, you're on the right path to <Constant name="fusion" /> readiness.

If everything works as expected, proceed to the next step to start upgrading your environments. If you encounter deprecation warnings, don't fear! We'll address those [later in this guide](/guides/prepare-fusion-upgrade?step=4). If you encounter errors, revert to your previous version and refer to the [version upgrade guides](/docs/dbt-versions/core-upgrade) to resolve any differences between your current version and the latest available <Constant name="core" /> version.

### Step 2: Upgrade your development environment

After successfully testing your individual development environment with the override, upgrade the development environment for the entire project (be sure to give your team notice!):

1. Navigate to **Environments** in your project settings.
2. Select your **Development** environment and click **Edit**.
3. Click the **dbt version** dropdown and select **Latest**.
4. Click **Save** to apply the changes.

<Lightbox src="/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/choosing-dbt-version/select-development.png" width="90%" title="Upgrade development environment to Latest dbt Core release track"/>

:::info Remove your override

Once your development environment is upgraded, you can remove your personal override by returning to your account credentials and selecting the same version as your environment.

:::

### Step 3: Upgrade staging and pre-production

If your organization has staging or pre-production environments, upgrade these before production:

1. Navigate to **Environments** and select your staging/pre-production environment.
2. Click **Edit** and select **Latest** from the **dbt version** dropdown.
3. Click **Save**.
4. Run your jobs in this environment for a few days to validate everything works correctly.

This provides a final validation layer before upgrading production environments.

### Step 4: Upgrade your production environment

After validating in staging (or development if you don't have staging), upgrade your production environment:

1. Navigate to **Environments** and select your **Production** environment.
2. Click **Edit** and select **Latest** from the **dbt version** dropdown.
3. Click **Save** to apply the changes.
4. Monitor your first few production runs to ensure everything executes successfully.


### Step 5: Update jobs

While environments control the dbt version for most scenarios, some older job configurations may have version overrides. Review your jobs and [update any that specify a dbt version](/docs/dbt-versions/upgrade-dbt-version-in-cloud#jobs) to ensure they use the environment's Latest release track.

## Resolve all deprecation warnings

<Constant name="fusion" /> enforces strict validation and won't accept deprecated code that currently generates warnings in <Constant name="core" />. You must resolve all deprecation warnings before upgrading to <Constant name="fusion" />. Fortunately, the autofix tool in the <Constant name="studio_ide" /> can automatically resolve most common deprecations for you.

:::tip VS Code extension

This guide provides steps to resolve deprecation warnings without leaving <Constant name="dbt_platform" />. If you prefer to work in the VS Code or Cursor editors locally, you can run the autofix in our dbt VS Code extension. Check out the [installation guide](/docs/install-dbt-extension) for more information about those workflows.

:::

### What the autofix tool handles

The autofix tool can resolve many deprecations automatically, including:

- Moving custom configurations into the `meta` dictionary
- Fixing duplicate YAML keys
- Correcting unrecognized resource properties
- Updating deprecated configuration patterns

Check out the [autofix readme](https://github.com/dbt-labs/dbt-autofix/) for a complete list of the deprecations it addresses.

:::note Fusion package compatibility

In addition to deprecations, the autofix tool attempts to upgrade packages to the lowest supported <Constant name="fusion" />-compatible version. Check out [package support](/docs/fusion/supported-features#package-support) for more information about <Constant name="fusion" /> compatibility.

:::

### Step 1: Create a new branch

Before running the autofix tool, create a new branch to isolate your changes:

1. Navigate to the <Constant name="studio_ide" /> by clicking **Studio** in the left-side menu.
2. Click the **Version control** panel (git branch icon) on the left sidebar.
3. Click **Create branch** and name it something descriptive like `fusion-deprecation-fixes`.
4. Click **Create** to switch to your new branch.

:::warning Save before autofixing

The autofix tool will modify files in your project. Make sure to commit or stash any unsaved work to avoid losing changes.

:::

### Step 2: Run the autofix tool

Now you're ready to scan for and automatically fix deprecation warnings:

1. Click the **three-dot menu** in the bottom right corner of the <Constant name="studio_ide" />.
2. Select **Check & fix deprecations**.

<Lightbox src="/img/docs/dbt-cloud/cloud-ide/ide-options-menu-with-save.png" width="90%" title="Access the Studio IDE options menu"/>

The tool runs `dbt parse --show-all-deprecations --no-partial-parse` to identify all deprecations in your project. This may take a few moments depending on your project size.

3. When parsing completes, view the results in the **Command history** panel in the bottom left.

<Lightbox src="/img/docs/dbt-cloud/cloud-ide/command-history.png" width="90%" title="View command history and deprecation results"/>

### Step 3: Review and apply autofixes

After the deprecation scan completes, review the findings and apply automatic fixes:

1. In the **Command history** panel, review the list of deprecation warnings.
2. Click the **Autofix warnings** button to proceed.

<Lightbox src="/img/docs/dbt-cloud/cloud-ide/autofix-button.png" width="90%" title="Click Autofix warnings to resolve deprecations automatically"/>

3. In the **Proceed with autofix** dialog, review the warning and click **Continue**.

<Lightbox src="/img/docs/dbt-cloud/cloud-ide/proceed-with-autofix.png" width="90%" title="Confirm autofix operation"/>

The tool automatically modifies your project files to resolve fixable deprecations, then runs another parse to identify any remaining warnings.

4. When complete, a success message appears. Click **Review changes**.

<Lightbox src="/img/docs/dbt-cloud/cloud-ide/autofix-success.png" width="90%" title="Autofix complete"/>

### Step 4: Verify the changes

Review the changes made by the autofix tool to ensure they're correct:

1. Open the **Version control** panel to view all modified files.
2. Click on individual files to review the specific changes.
3. Look for files with moved configurations, corrected properties, or updated syntax.
4. If needed, make any additional manual adjustments.

### Step 5: Commit your changes

Once you're satisfied with the autofix changes, commit them to your branch:

1. In the **Version control** panel, add a descriptive commit message like "Fix deprecation warnings for Fusion upgrade".
2. Click **Commit and sync** to save your changes.

### Step 6: Address remaining deprecations

If the autofix tool reports remaining deprecation warnings that couldn't be automatically fixed:

1. Review the warning messages in the **Command history** panel. Each warning includes the file path and line number.
2. Manually update the code based on the deprecation guidance:
   - Custom inputs should be moved to the `meta` config.
   - Deprecated properties should be updated to their new equivalents.
   - Refer to specific [version upgrade guides](/docs/dbt-versions/core-upgrade) for detailed migration instructions.
3. After making manual fixes, run **Check & fix deprecations** again to verify all warnings are resolved.
4. Commit your changes.

### Step 7: Merge to your main branch

Once all deprecations are resolved:

1. Create a pull request in your git provider to merge your deprecation fixes.
2. Have your team review the changes.
3. Merge the PR to your main development branch.
4. Ensure these changes are deployed to your environments before proceeding with the <Constant name="fusion" /> upgrade.

## Validate and upgrade your dbt packages

:::tip Run autofix first

This section contains instructions for manual package upgrades. We recommend running the autofix tool before taking these steps.

The autofix tool finds packages incompatible with <Constant name="fusion" /> and upgrades them to the lowest compatible version. For more information, check out [package support](/docs/fusion/supported-features#package-support).

:::

dbt packages extend your project's functionality, but they must be compatible with <Constant name="fusion" />. Most commonly used packages from dbt Labs (like `dbt_utils` and `dbt_project_evaluator`) and many community packages [already support <Constant name="fusion" />](/docs/fusion/supported-features#package-support). Before upgrading, verify your packages are compatible and upgrade them to the latest versions. Check for packages that support version 2.0.0, or ask the maintainer if you're unsure.

What if a package isn't compatible?

If a critical package isn't yet compatible with <Constant name="fusion" />:
- Check with the package maintainer about their roadmap.
- Open an issue requesting <Constant name="fusion" /> support.
- Consider contributing the compatibility updates yourself.
- Try it out anyway! The incompatible portion of the package might not impact your project. 

import FusionPackageCompatibility from '/snippets/_fusion-package-compatibility.md';

<FusionPackageCompatibility />

### Step 1: Review your current packages

Identify which packages your project uses:

1. In the <Constant name="studio_ide" />, open your project's root directory.
2. Look for either `packages.yml` or `dependencies.yml` file.
3. Review the list of packages and their current versions.

Your file will look something like this:

```yaml
packages:
  - package: dbt-labs/dbt_utils
    version: 1.0.0
  - package: dbt-labs/codegen
    version: 0.9.0
```

### Step 2: Check compatibility and find the latest package versions

Review [the dbt package hub](https://hub.getdbt.com) to see verified <Constant name="fusion" />-compatible packages by checking that the `require-dbt-version` configuration includes `2.0.0` or higher. Refer to [package support](/docs/fusion/supported-features#package-support) for more information.

For packages that aren't <Constant name="fusion" />-compatible:
   - Visit the package's GitHub repository.
   - Check the README or recent releases for <Constant name="fusion" /> compatibility information.
   - Look for issues or discussions about <Constant name="fusion" /> support.

For each package, find the most recent version:

- Visit [dbt Hub](https://hub.getdbt.com) for packages hosted there.
- For packages from GitHub, check the repository's releases page.
- Note the latest version number for each package you use.

For Hub packages, you can use version ranges to stay up-to-date:

```yaml
packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.0.0", "<3.0.0"]  # Gets latest 1.x or 2.x version
```

### Step 3: Update your package versions

Update your `packages.yml` or `dependencies.yml` file with the latest compatible versions:

1. In the <Constant name="studio_ide" />, open your `packages.yml` or `dependencies.yml` file.
2. Update each package version to the latest compatible version.
3. Save the file.

   Before update:
   ```yaml
   packages:
   - package: dbt-labs/dbt_utils
      version: 0.9.6
   - package: dbt-labs/codegen
      version: 0.9.0
   ```

   After update:
   ```yaml
   packages:
   - package: dbt-labs/dbt_utils
      version: [">=1.0.0", "<2.0.0"]
   - package: dbt-labs/codegen
      version: [">=0.12.0", "<1.0.0"]
   ```

### Step 4: Install updated packages

After updating your package versions, install them:

1. In the <Constant name="studio_ide" /> command line, run:
   ```bash
   dbt deps --upgrade
   ```

The `--upgrade` flag ensures dbt installs the latest versions within your specified ranges, updating the `package-lock.yml` file.

2. Review the output to confirm all packages installed successfully.
3. Check that the `package-lock.yml` file was updated with the new package versions.

:::info About package-lock.yml

The `package-lock.yml` file pins your packages to specific versions for reproducible builds. We recommend committing this file to version control so your entire team uses the same package versions.

:::

### Step 5: Test your project with updated packages

After upgrading packages, test your project to ensure everything works:

1. Run a subset of your models to verify basic functionality:
   ```bash
   dbt run --select tag:daily
   ```

2. Run your tests to catch any breaking changes (exact command may vary):
   ```bash
   dbt test
   ```

3. If you encounter issues:
   - Review the package's changelog for breaking changes
   - Adjust your code to match new package behavior
   - If problems persist, temporarily pin to an older compatible version (if possible)

### Step 6: Commit package updates

Once you've verified the updated packages work correctly:

1. In the **Version control** panel, stage your changes:
   - `packages.yml` or `dependencies.yml`
   - `package-lock.yml`

2. Add a commit message like "Upgrade dbt packages for Fusion compatibility".
3. Click **Commit and sync**.

## Update your jobs

Use the <Constant name="fusion" /> readiness panel to validate your jobs against the <Constant name="fusion_engine" /> and fix any issues you find.

### Review your jobs

The readiness panel shows how many jobs are ineligible for <Constant name="fusion" /> or have an unknown eligibility status:

:::note
If a job has not run in the last 7 days, you must run it once for the debugging options to be available.
:::

1. Open the jobs list using either path:
   - From the main menu, go to **Orchestration** → **Jobs**.
   - From the readiness panel, click **Review jobs**.
   <Lightbox src="/img/fusion/review-jobs.png" width="60%" title="Shortcut to review your jobs from the readiness panel"/>
2. Find the <Constant name="fusion" /> eligibility icon to the right of your jobs. Click **Review job** for  any job that is ineligible or has an unknown eligibility status.
   <Lightbox src="/img/fusion/job-eligibility.png" width="60%" title="Take action on your jobs to make them Fusion eligible."/>
3. Click **Debug on Fusion** and choose one of the following:
   - [Debug in Studio](#debug-in-studio)
   - [Debug in Studio with Copilot](#debug-in-studio-with-copilot)
   - [Run once on Fusion](#run-once-on-fusion)


#### Debug in Studio

In the <Constant name="studio_ide" />, run <Constant name="fusion" /> in your development environment to review project warnings and errors:

1. Click **Debug in Studio**. The <Constant name="studio_ide" /> opens and selects the **Problems** tab.

2. dbt sets only your development environment to <Constant name="fusion" />.

<Lightbox src="/img/fusion/fusion-ide.png" width="60%" title="Running Fusion in development"/>

3. Review the warnings or errors in the **Problems** tab.
4. Fix the issues directly or run the [autofix tool](/docs/cloud/studio-ide/autofix-deprecations).
5. When the project runs with no warnings or errors, commit and publish your changes.
6. After you merge the changes, wait for the job to run again or run it manually.

#### Debug in Studio with Copilot <Lifecycle status="beta" size="80%" />

import FusionMigrationWorkflow from '/snippets/_fusion-migration-workflow.md';

<FusionMigrationWorkflow />

#### Run once on Fusion

When you are confident a job is ready for <Constant name="fusion" />, you can run it once on the engine without changing environment-wide settings:

1. Click **Run once on Fusion**.
2. The job window opens and dbt runs the job on <Constant name="fusion" /> without changing other jobs or environment settings.
3. When the job succeeds, click **Override eligibility status** to update the eligibility status.
   <Lightbox src="/img/fusion/eligibility-status.png" width="60%" title="Override the eligibility status of a successful job."/>

Congratulations! You have validated <Constant name="fusion" /> eligibility for your jobs.

<Lightbox src="/img/fusion/fusion-eligible.png" width="60%" title="Your job is now ready for Fusion!"/>

## What's next? 

With limitations identified and addressed, you've completed all the preparation steps. Your project is now ready to upgrade to <Constant name="fusion" />!

Check out [Part 2: Making the move](/guides/upgrade-to-fusion)
