dbt Fusion Package Compatibility

dbt Fusion is the Rust-based rewrite of the dbt core engine, released as dbt 2.0.0. It delivers approximately 30x faster parsing and compilation compared to dbt Core’s Python-based engine. For most SQL logic, Fusion is a drop-in upgrade. For packages, it introduces a compatibility wall — notably a changed manifest format and version-bound conflicts.

The Version Landscape

The dbt version history has a few inflection points relevant to packages:

For package users, 1.8 matters because it changed tests: to data_tests:. Packages that haven’t been updated may still use the old key, which generates deprecation warnings on 1.8+ and will eventually break. Check your installed packages’ YAML if you’re seeing deprecation warnings.

Fusion 2.0 is the biggest compatibility break. It’s not just a version number — it uses a fundamentally different manifest format.

The Manifest Incompatibility

dbt Core produces manifest v12. dbt Fusion produces manifest v20. These are not compatible. Tools that consume dbt manifests — CI systems, observability platforms, IDE integrations, some orchestrators — may break when you switch to Fusion if they haven’t updated to handle v20.

More relevant for packages: the manifest format change means Fusion cannot use artifacts produced by Core, and vice versa. If you’re testing a Fusion migration in parallel with a Core production environment, they cannot share artifacts. You need separate environments.

The require-dbt-version Problem

The most common Fusion compatibility issue is packages with version bounds that exclude 2.x:

# dbt_project.yml in the package
require-dbt-version: [">=1.0.0", "<2.0.0"]

This range explicitly excludes Fusion 2.0.0. When you try to run Fusion against a project with this package, you get:

Error: Package requires dbt version >=1.0.0, <2.0.0 but got 2.0.0

The fix for package maintainers is extending the upper bound:

require-dbt-version: [">=1.3.0", "<3.0.0"]

As a package user, you can’t fix this yourself — you’re stuck waiting for the package maintainer to update the bounds and cut a new release. This is the primary reason to check the Fusion compatibility badge before planning a migration.

The Fusion Compatibility Badge

The dbt Hub now shows a Fusion compatibility badge on packages that have been verified to work with dbt 2.0+. The badge appears when a package:

• Has require-dbt-version set to include the 2.x range
• Has been tested against Fusion by the maintainer or dbt Labs

Major packages are already Fusion-compatible: dbt-utils, all Fivetran packages, dbt-audit-helper, dbt-expectations, Elementary. For community packages, check the badge before assuming compatibility.

The badge is a signal, not a guarantee. A package can have correct version bounds but still have SQL that Fusion parses differently, or use Jinja patterns that the Rust engine handles inconsistently. The badge tells you the maintainer has done some validation; your own integration tests tell you whether it works in your specific project.

dbt-autofix

The dbt-autofix tool helps migrate deprecated configurations automatically. Before testing Fusion, run it to catch the most common low-hanging issues:

pip install dbt-autofix
dbt-autofix --target-version 2.0.0

It handles things like:

• Renaming tests: to data_tests: in model YAML
• Updating deprecated macro syntax
• Flagging require-dbt-version bounds that exclude 2.x

autofix handles the mechanical changes. The deeper issues — manifest v20 incompatibility with downstream tools, packages with unsupported version bounds — require manual attention.

A Fusion Migration Checklist

If you’re planning to migrate a project with packages to Fusion:

1. Run dbt-autofix to catch deprecated syntax in your project
2. Audit each package in your packages.yml for the Fusion badge
3. Check require-dbt-version in installed packages (look in dbt_packages/{package}/dbt_project.yml)
4. Audit downstream tools — anything consuming dbt manifests needs to support v20
5. Run your test suite against Fusion in a staging environment before cutting over production
6. Pin the lock file after migration so the known-good versions are recorded

Migrate production and packages separately. Upgrade to the latest dbt Core 1.x first (where packages are most compatible), then test Fusion in a parallel environment against the same package versions.

For Package Maintainers

If you’re maintaining a package and want to claim Fusion compatibility:

1. Update require-dbt-version: [">=1.3.0", "<3.0.0"] in your dbt_project.yml
2. Add Fusion to your CI matrix — test against both dbt 1.x and 2.0.0 on each release
3. Update any tests: keys to data_tests: in your model YAML
4. Submit to the Hub for the compatibility badge

The <3.0.0 upper bound covers both runtimes. The CI matrix catches any Jinja or SQL patterns that Fusion handles differently from Core.

See dbt Package Anti-Patterns for the full discussion of require-dbt-version and why missing or over-tight bounds cause problems for users.