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, dbt sends a helpful error message for any user who attempts to run the project with an unsupported version of dbt. This can be useful for package maintainers (such as dbt-utils) to ensure that users' dbt version is compatible with the package. Setting this configuration might also help your whole team remain synchronized on the same version of dbt for local development, to avoid compatibility issues from changed behaviour.

If this configuration is not specified, no version check will occur.

Versionless

Starting in 2024, when you select Versionless in dbt Cloud, dbt will ignore the require-dbt-version config. Refer to Versionless for more details.

dbt Labs is committed to zero breaking changes for code in dbt projects, with ongoing releases to dbt Cloud 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. Since v1.7, 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

Examples

Specify a minimum dbt version

Use a >= operator for a minimum boundary. In the following example, this project will run with any version of dbt greater than or equal to 1.0.0.

dbt_project.yml

require-dbt-version: ">=1.0.0"

Pin to a range

Use a comma separated list for an upper and lower bound. In the following example, this project will run with dbt 1.x.x.

dbt_project.yml

require-dbt-version: [">=1.0.0", "<2.0.0"]

OR

dbt_project.yml

require-dbt-version: ">=1.0.0,<2.0.0"

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=0.21.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: =0.21.0
    Required version of dbt for 'my_project': ['>=1.0.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=0.21.0
Found 13 models, 2 tests, 1 archives, 0 analyses, 204 macros, 2 operations....

See global configs for usage details.

Recommendation

• This is a recommended configuration
• Before v1, you should pin your required dbt version to a minor release. After v1, you should pin to a major release (see above example)