About flags (global configs)

In dbt, "flags" (also called "global configs" and often configured with environment variables) are settings for fine-tuning how dbt runs your project. They differ from resource-specific configs that tell dbt 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.

You can use flags with the dbt Fusion engine or dbt Core engine through the CLI during local development or in dbt platform.

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 by using 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".

You can configure flags in dbt_project.yml, environment variables, and CLI options. For details, refer to environment variable configs.

Setting flags

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

• CLI options: Define behavior specific to this invocation. Supported for all dbt commands.
• 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).
• Project-level flags in dbt_project.yml: Define version-controlled defaults for everyone running this project. Also, opt in or out of behavior changes to manage your migration off legacy functionality.
• User settings (~/.dbt/user_settings.yml): Define personal preferences that apply across all projects on your machine. Written automatically by dbt login.

The most specific setting "wins." CLI options take the highest precedence, followed by environment variables, then dbt_project.yml, and finally user_settings.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

(Applies to dbt v1.11 and later)

# set this environment variable to 'True' (bash syntax)
export DBT_ENGINE_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 ((Applies to dbt v1.11 and later) DBT_ENGINE_LOG_PATH and DBT_ENGINE_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.

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 }}'

Available flags

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.

Use this table to compare all available flags and how to configure them across interfaces:

• dbt CLI: Indicates whether the flag is supported in the dbt platform-supported CLI.
• Type / default: Shows the accepted value type and default.
• In project: Indicates whether you can set the flag in dbt_project.yml.
• Env var: Shows the corresponding environment variable name, when available. In general, v1.10 and earlier use the DBT_ prefix, while v1.11+ uses the DBT_ENGINE_ prefix.
• CLI flags: Lists command-line options for setting the flag for a specific invocation.

(Applies to dbt v1.11 and later)

Flag	dbt CLI?	Type / default	In project?	Env var	CLI flags
cache_selected_only	✅	boolean default: False	✅	DBT_ENGINE_CACHE_SELECTED_ONLY	--cache-selected-only --no-cache-selected-only
clean_project_files_only	❌	boolean default: True	❌	DBT_ENGINE_CLEAN_PROJECT_FILES_ONLY	--clean-project-files-only --no-clean-project-files-only
debug	✅	boolean default: False	✅	DBT_ENGINE_DEBUG	--debug --no-debug
defer	✅ (default)	boolean default: False	❌	DBT_ENGINE_DEFER	--defer --no-defer
defer_state	❌	path default: None	❌	DBT_ENGINE_DEFER_STATE	--defer-state
favor_state	✅	boolean default: False	❌	DBT_ENGINE_FAVOR_STATE	--favor-state --no-favor-state
empty	✅	boolean default: False	❌	DBT_ENGINE_EMPTY	--empty --no-empty
event_time_start	✅	datetime default: None	❌	DBT_ENGINE_EVENT_TIME_START	--event-time-start
event_time_end	✅	datetime default: None	❌	DBT_ENGINE_EVENT_TIME_END	--event-time-end
fail_fast	✅	boolean default: False	✅	DBT_ENGINE_FAIL_FAST	--fail-fast -x --no-fail-fast
full_refresh	✅	boolean default: False	✅ (as resource config)	DBT_ENGINE_FULL_REFRESH	--full-refresh --no-full-refresh
hints_enabled (v1.12+)	✅	boolean default: True	✅	DBT_ENGINE_HINTS_ENABLED	--hints-enabled --no-hints-enabled
indirect_selection	❌	enum default: eager	✅	DBT_ENGINE_INDIRECT_SELECTION	--indirect-selection
introspect	❌	boolean default: True	❌	DBT_ENGINE_INTROSPECT	--introspect --no-introspect
log_cache_events	❌	boolean default: False	❌	DBT_ENGINE_LOG_CACHE_EVENTS	--log-cache-events --no-log-cache-events
log_format_file	❌	enum default: default (text)	✅	DBT_ENGINE_LOG_FORMAT_FILE	--log-format-file
log_format	❌	enum default: default (text)	✅	DBT_ENGINE_LOG_FORMAT	--log-format
log_level_file	❌	enum default: debug	✅	DBT_ENGINE_LOG_LEVEL_FILE	--log-level-file
log_level	❌	enum default: info	✅	DBT_ENGINE_LOG_LEVEL	--log-level
log_path	❌	path default: None (uses logs/)	❌	DBT_ENGINE_LOG_PATH	--log-path
manage_state (v2.0+)	✅	boolean default: False	✅	DBT_ENGINE_MANAGE_STATE	--manage-state --no-manage-state
partial_parse	✅	boolean default: True	✅	DBT_ENGINE_PARTIAL_PARSE	--partial-parse --no-partial-parse
populate_cache	✅	boolean default: True	✅	DBT_ENGINE_POPULATE_CACHE	--populate-cache --no-populate-cache
print	❌	boolean default: True	❌	DBT_ENGINE_PRINT	--print --no-print
printer_width	❌	int default: 80	✅	DBT_ENGINE_PRINTER_WIDTH	--printer-width
profile	❌	string default: None	✅ (as top-level key)	DBT_ENGINE_PROFILE	--profile
profiles_dir	❌	path default: None (current dir, then HOME dir)	❌	DBT_ENGINE_PROFILES_DIR	--profiles-dir
project_dir	❌	path default: (empty)	❌	DBT_ENGINE_PROJECT_DIR	--project-dir
quiet	✅	boolean default: False	❌	DBT_ENGINE_QUIET	--quiet
resource-type (v1.8+)	✅	string default: None	❌	DBT_ENGINE_RESOURCE_TYPES DBT_ENGINE_EXCLUDE_RESOURCE_TYPES	--resource-type --exclude-resource-type
sample	✅	string default: None	❌	DBT_ENGINE_SAMPLE	--sample
send_anonymous_usage_stats	❌	boolean default: True	✅	DBT_ENGINE_SEND_ANONYMOUS_USAGE_STATS	--send-anonymous-usage-stats --no-send-anonymous-usage-stats
source_freshness_run_project_hooks	❌	boolean default: True	✅	❌	❌
sqlparse	❌	YAML map default: MAX_GROUPING_DEPTH and MAX_GROUPING_TOKENS set to null	❌	DBT_ENGINE_SQLPARSE	--sqlparse
state	❌	path default: none	❌	DBT_ENGINE_STATE, DBT_ENGINE_DEFER_STATE	--state --defer-state
static_parser	❌	boolean default: True	✅	DBT_ENGINE_STATIC_PARSER	--static-parser --no-static-parser
store_failures	✅	boolean default: False	✅ (as resource config)	DBT_ENGINE_STORE_FAILURES	--store-failures --no-store-failures
target_path	❌	path default: None (uses target/)	❌	DBT_ENGINE_TARGET_PATH	--target-path
target	❌	string default: None	❌	DBT_ENGINE_TARGET	--target
use_colors_file	❌	boolean default: True	✅	DBT_ENGINE_USE_COLORS_FILE	--use-colors-file --no-use-colors-file
use_colors	❌	boolean default: True	✅	DBT_ENGINE_USE_COLORS	--use-colors --no-use-colors
use_experimental_parser	❌	boolean default: False	✅	DBT_ENGINE_USE_EXPERIMENTAL_PARSER	--use-experimental-parser --no-use-experimental-parser
use_v2_parser	✅	boolean default: False	✅	DBT_ENGINE_USE_V2_PARSER	--use-v2-parser
version_check	❌	boolean default: varies	✅	DBT_ENGINE_VERSION_CHECK	--version-check --no-version-check
warn_error_options	✅	dict default:	✅	DBT_ENGINE_WARN_ERROR_OPTIONS	--warn-error-options
warn_error	✅	boolean default: False	✅	DBT_ENGINE_WARN_ERROR	--warn-error
write_json	✅	boolean default: True	✅	DBT_ENGINE_WRITE_JSON	--write-json --no-write-json

Common flag examples

Use the --target flag to specify which target (environment) to use when running dbt commands. For example:

dbt run --target dev
dbt run --target prod
dbt build --target staging

The --target flag allows you to run the same dbt project against different environments without modifying your configuration files. Define the target in your profiles.yml file. Learn more about connection profiles and targets.

Was this page helpful?

Privacy policyCreate a GitHub issue

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