Skip to main content

About flags (global configs)

In dbt, "flags" (also called "global configs") are configurations for fine-tuning how dbt runs your project. They differ from resource-specific configs that tell dbt about what to run.

Flags control things like the visual output of logs, whether to treat specific warning messages as errors, or whether to "fail fast" after encountering the first error. Flags are "global" configs because they are available for all dbt commands and they can be set in multiple places.

There is a significant overlap between dbt's flags and dbt's command line options, but there are differences:

  • Certain flags can only be set in dbt_project.yml and cannot be overridden for specific invocations via CLI options.
  • If a CLI option is supported by specific commands, rather than supported by all commands ("global"), it is generally not considered to be a "flag".

Setting flags

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

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 into legacy dbt behaviors 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.

Accessing flags

Custom user-defined logic, written in Jinja, can check the values of flags using the flags context variable.

# dbt_project.yml

on-run-start:
- '{{ log("I will stop at the first sign of trouble", info = true) if flags.FAIL_FAST }}'

Because the values of flags can differ across invocations, we strongly advise against using flags as an input to configurations or dependencies (ref + source) that dbt resolves during parsing.

Available flags

Flag nameTypeDefaultSupported in project?Environment variableCommand line optionSupported in Cloud CLI?
cache_selected_onlybooleanFalseDBT_CACHE_SELECTED_ONLY--cache-selected-only, --no-cache-selected-only
debugbooleanFalseDBT_DEBUG--debug, --no-debug
deferbooleanFalseDBT_DEFER--defer, --no-defer✅ (enabled by default)
defer_statepathNoneDBT_DEFER_STATE--defer-state
fail_fastbooleanFalseDBT_FAIL_FAST--fail-fast, -x, --no-fail-fast
full_refreshbooleanFalse✅ (as resource config)DBT_FULL_REFRESH--full-refresh, --no-full-refresh
indirect_selectionenumeagerDBT_INDIRECT_SELECTION--indirect-selection
introspectbooleanTrueDBT_INTROSPECT--introspect, --no-introspect
log_cache_eventsbooleanFalseDBT_LOG_CACHE_EVENTS--log-cache-events, --no-log-cache-events
log_format_fileenumdefault (text)DBT_LOG_FORMAT_FILE--log-format-file
log_formatenumdefault (text)DBT_LOG_FORMAT--log-format
log_level_fileenumdebugDBT_LOG_LEVEL_FILE--log-level-file
log_levelenuminfoDBT_LOG_LEVEL--log-level
log_pathpathNone (uses logs/)DBT_PROFILES_DIR--profiles-dir
partial_parsebooleanTrueDBT_PARTIAL_PARSE--partial-parse, --no-partial-parse
populate_cachebooleanTrueDBT_POPULATE_CACHE--populate-cache, --no-populate-cache
printbooleanTrueDBT_PRINT--print
printer_widthint80DBT_PRINTER_WIDTH--printer-width
profilestringNone✅ (as top-level key)--profile
profiles_dirpathNone (current dir, then HOME dir)DBT_PROFILES_DIR--profiles-dir
project_dirpathDBT_PROJECT_DIR--project-dir
quietbooleanFalseDBT_QUIET--quiet
send_anonymous_usage_statsbooleanTrueDBT_SEND_ANONYMOUS_USAGE_STATS--send-anonymous-usage-stats, --no-send-anonymous-usage-stats
source_freshness_run_project_hooksbooleanFalse
statepathnoneDBT_STATE, DBT_DEFER_STATE--state, --defer-state
static_parserbooleanTrueDBT_STATIC_PARSER--static-parser, --no-static-parser
store_failuresbooleanFalse✅ (as resource config)DBT_STORE_FAILURES--store-failures, --no-store-failures
target_pathpathNone (uses target/)DBT_TARGET_PATH--target-path
targetstringNone--target
use_colors_filebooleanTrueDBT_USE_COLORS_FILE--use-colors-file, --no-use-colors-file
use_colorsbooleanTrueDBT_USE_COLORS--use-colors, --no-use-colors
use_experimental_parserbooleanFalseDBT_USE_EXPERIMENTAL_PARSER--use-experimental-parser, --no-use-experimental-parser
version_checkbooleanvariesDBT_VERSION_CHECK--version-check, --no-version-check
warn_error_optionsdict{}DBT_WARN_ERROR_OPTIONS--warn-error-options
warn_errorbooleanFalseDBT_WARN_ERROR--warn-error, --no-warn-error
write_jsonbooleanTrueDBT_WRITE_JSON--write-json, --no-write-json
0