Project flags

dbt_project.yml

flags:
  <global_config>: <value>

Reference the table of all flags to see which global configs are available for setting in dbt_project.yml.

The flags dictionary is the only place you can opt out of behavior changes, while the legacy behavior is still supported.

Config precedence

There are multiple ways of setting flags, which depend on the use case:

• Project-level flags in dbt_project.yml: Define version-controlled defaults for everyone running this project. Also, opt in or opt out of behavior changes to manage your migration off legacy functionality.
• Environment variables: Define different behavior in different runtime environments (development vs. production vs. continuous integration, or different behavior for different users in development (based on personal preferences).
• CLI options: Define behavior specific to this invocation. Supported for all dbt commands.

The most specific setting "wins." If you set the same flag in all three places, the CLI option will take precedence, followed by the environment variable, and finally, the value in dbt_project.yml. If you set the flag in none of those places, it will use the default value defined within dbt.

Most flags can be set in all three places:

# dbt_project.yml
flags:
  # set default for running this project -- anywhere, anytime, by anyone
  fail_fast: true

# set this environment variable to 'True' (bash syntax)
export DBT_FAIL_FAST=1
dbt run

dbt run --fail-fast # set to True for this specific invocation
dbt run --no-fail-fast # set to False

There are two categories of exceptions:

1. Flags setting file paths: Flags for file paths that are relevant to runtime execution (for example, --log-path or --state) cannot be set in dbt_project.yml. To override defaults, pass CLI options or set environment variables (DBT_LOG_PATH, DBT_STATE). Flags that tell dbt where to find project resources (for example, model-paths) are set in dbt_project.yml, but as a top-level key, outside the flags dictionary; these configs are expected to be fully static and never vary based on the command or execution environment.
2. Opt-in flags: Flags opting in or out of behavior changes can only be defined in dbt_project.yml. These are intended to be set in version control and migrated via pull/merge request. Their values should not diverge indefinitely across invocations, environments, or users.