Skip to main content

require-dbt-version

dbt_project.yml
require-dbt-version: version-range | [version-range]

Definition​

You can use require-dbt-version to restrict your project to only work with a range of dbt versions.

When you set this configuration:

  • If you have installed packages from the dbt Packages hub that specify a require_dbt_version that doesn't match, running dbt commands will result in an error.
  • It helps package maintainers (such as dbt-utils) ensure that users' dbt version is compatible with the package.
  • It signals compatibility with dbt Fusion Engine (2.0.0 and higher).
  • It might also help your whole team remain synchronized on the same version of dbt for local development, to avoid compatibility issues from changed behavior.

You must pin to a major release. See pin to a range for more details. If this configuration isn't specified, no version check will occur.

dbt release tracks

Starting in 2024, when you select a release track in dbt to receive ongoing dbt version upgrades, dbt will ignore the require-dbt-version config.

dbt Labs is committed to zero breaking changes for code in dbt projects, with ongoing releases to dbt and new versions of dbt Core. We also recommend these best practices:

 Installing dbt packages

If you install dbt packages for use in your project, whether the package is maintained by your colleagues or a member of the open source dbt community, we recommend pinning the package to a specific revision or version boundary. dbt manages this out-of-the-box by locking the version/revision of packages in development in order to guarantee predictable builds in production. To learn more, refer to Predictable package installs.

 Maintaining dbt packages

If you maintain dbt packages, whether on behalf of your colleagues or members of the open source community, we recommend writing defensive code that checks to verify that other required packages and global macros are available. For example, if your package depends on the availability of a date_spine macro in the global dbt namespace, you can write:

models/some_days.sql
{% macro a_few_days_in_september() %}

    {% if not dbt.get('date_spine') %}
      {{ exceptions.raise_compiler_error("Expected to find the dbt.date_spine macro, but it could not be found") }}
    {% endif %}

    {{ date_spine("day", "cast('2020-01-01' as date)", "cast('2030-12-31' as date)") }}

{% endmacro %}

YAML quoting​

This configuration needs to be interpolated by the YAML parser as a string. As such, you should quote the value of the configuration, taking care to avoid whitespace. For example:

# ✅ These will work
require-dbt-version: ">=1.0.0" # Double quotes are OK
require-dbt-version: '>=1.0.0' # So are single quotes

# ❌ These will not work
require-dbt-version: >=1.0.0 # No quotes? No good
require-dbt-version: ">= 1.0.0" # Don't put whitespace after the equality signs

Avoid unbounded upper limits​

We recommend defining both lower and upper bounds, such as ">=1.0.0,<3.0.0", to ensure stability across releases. We don't recommend having an unbounded require-dbt-version (for example, ">=1.0.0"). Without an upper limit, a project may break when dbt releases a new major version.

Fusion compatibility​

The require-dbt-version also signals whether a project or package supports the dbt Fusion Engine (2.0.0 and higher).

  • If it excludes 2.0.0, Fusion will warn today and error in a future release, matching dbt Core behavior.
  • You can bypass version checks with --no-version-check.

Refer to pin to a range for more info on how to define a version range.§

 Use dbt-autofix to update dbt projects and packages

dbt-autofix tool automatically scans your dbt project for deprecated configurations and updates them to align with the latest best practices and prepare for Fusion migration. When it runs, it'll also check your packages.yml to determine which packages it can automatically upgrade:

  • Fusion compatibility — dbt-autofix checks whether a package’s require-dbt-version includes 2.0.0 or higher, signaling Fusion support.
  • Package eligibility — dbt-autofix automatically checks if a package is Fusion-eligible (with require-dbt-version including 2.0.0 or higher) and verified safe for upgrade.
  • Upgrade logic — If both checks pass, the tool upgrades the package to the lowest Fusion-compatible version.

This ensures that dbt-autofix only updates packages that are confirmed to work with Fusion and avoids updating packages that are known to be incompatible with Fusion.

Examples​

The following examples showcase how to use the require-dbt-version:

Specify a minimum dbt version​

Use a >= operator to specify a lower and an upper limit. For example:

dbt_project.yml
require-dbt-version: ">=1.9.0" # project will only work with versions 1.9 and higher.
require-dbt-version: ">=2.0.0" # project will only work with Fusion-compatible versions of dbt/packages.

Remember, having an unbounded upper limit isn't recommended. Instead, check out the pin to a range example to define a range with both a lower and upper limit to ensure stability across releases.

Pin to a range​

Use a comma separated list for an upper and lower bound. You can define a version range either as a YAML list (using square brackets) or as a comma-delimited string — both forms are valid and work.

To signal compatibility with the dbt Fusion Engine, include 2.0.0 or higher in your version range. Both of the following formats are valid:

dbt_project.yml
require-dbt-version: [">=1.10.0", "<3.0.0"]

# or

require-dbt-version: ">=1.10.0,<3.0.0"

If your range excludes 2.0.0 (for example, >=1.6.0,<2.0.0), Fusion will show a warning now and error in a future release. You can bypass version checks with --no-version-check.

Require a specific dbt version​

Not recommended

Pinning to a specific dbt version is discouraged because it limits project flexibility and can cause compatibility issues, especially with dbt packages. It's recommended to pin to a major release, using a version range (for example, ">=1.0.0", "<2.0.0") for broader compatibility and to benefit from updates.

While you can restrict your project to run only with an exact version of dbt Core, we do not recommend this for dbt Core v1.0.0 and higher.

In the following example, the project will only run with dbt v1.5:

dbt_project.yml
require-dbt-version: "1.5.0"

Invalid dbt versions​

If the version of dbt used to invoke a project disagrees with the specified require-dbt-version in the project or any of the included packages, then dbt will fail immediately with the following error:

$ dbt compile
Running with dbt=1.5.0
Encountered an error while reading the project:
Runtime Error
  This version of dbt is not supported with the 'my_project' package.
    Installed version of dbt: =1.5.0
    Required version of dbt for 'my_project': ['>=1.6.0', '<2.0.0']
  Check the requirements for the 'my_project' package, or run dbt again with --no-version-check

Disabling version checks​

To suppress failures to to incompatible dbt versions, supply the --no-version-check flag to dbt run.

$ dbt run --no-version-check
Running with dbt=1.5.0
Found 13 models, 2 tests, 1 archives, 0 analyses, 204 macros, 2 operations....

See global configs for usage details.

Was this page helpful?

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

0
Edit this page