---
title: "Using defer in dbt"
source: dbt Core Documentation
source_url: https://github.com/dbt-labs/docs.getdbt.com
licence: Apache-2.0
domain: data-and-analysis
subdomain: dbt-docs
date_added: 2026-04-25
---

[Defer](/reference/node-selection/defer) is a powerful feature that allows developers to only build, run, and test models<VersionBlock firstVersion="1.11"> and functions</VersionBlock> they've edited, without having to build and run all the models<VersionBlock firstVersion="1.11"> and functions</VersionBlock> that come before them (upstream parents). dbt powers this by using a production manifest for comparison and resolves `{{ ref() }}`<VersionBlock firstVersion="1.11"> and `{{ function() }}`</VersionBlock> calls with upstream production artifacts.

Both the <Constant name="studio_ide" /> and the <Constant name="dbt" /> CLI enable users to natively defer to production metadata directly in their development workflows. 

<Lightbox src src="/img/docs/reference/defer-diagram.png" width="50%" title="Use 'defer' to modify end-of-pipeline models by pointing to production models, instead of running everything upstream." />

When using `--defer`, <Constant name="dbt" /> will follow this order of execution for resolving `{{ ref() }}`<VersionBlock firstVersion="1.11"> and `{{ function() }}`</VersionBlock> calls.

1. If a development version of a deferred relation exists, dbt preferentially uses the development database location when resolving the reference.
2. If a development version doesn't exist, dbt uses the staging locations of parent relations based on metadata from the staging environment.
3. If no development version and no staging environment exist, dbt uses the production locations of parent relations based on metadata from the production environment. Note that dbt only defers to one environment per invocation &mdash; either staging or production.

**Note:** Passing the `--favor-state` flag will always resolve refs using staging metadata if available; otherwise, it defaults to production metadata regardless of the presence of a development relation, skipping step #1.

For a clean slate, it's a good practice to drop the development schema at the start and end of your development cycle.

If you require additional controls over production data, create a [staging environment](/docs/deploy/deploy-environments#staging-environment), and dbt will use that, rather than the production environment, to resolve `{{ ref() }}`<VersionBlock firstVersion="1.11"> and `{{ function() }}`</VersionBlock> calls.

## Required setup

- You must select the **[Production environment](/docs/deploy/deploy-environments#set-as-production-environment)** checkbox in the **Environment Settings** page. 
  - This can be set for one deployment environment per <Constant name="dbt" /> project.
- You must have a successful job run first.

When using defer, it compares artifacts from the most recent successful production job, excluding CI jobs.

### Defer in the dbt IDE

To use deferral in the <Constant name="studio_ide" />, you must have production artifacts generated by a deploy job. <Constant name="dbt" /> will first check for these artifacts in your Staging environment (if available), or else in the Production environment. 

The defer feature in the <Constant name="studio_ide" /> won't work if a Staging environment exists but no deploy job has run. This is because the necessary metadata to power defer won't exist until a deploy job has run successfully in the Staging environment.

To enable defer in the <Constant name="studio_ide" />, toggle the **Defer to staging/production** button on the command bar. Once enabled, <Constant name="dbt" /> will:

1. Pull down the most recent manifest from the staging or production environment for comparison
2. Pass the `--defer` flag to the command (for any command that accepts the flag)

For example, if you were to start developing on a new branch with [nothing in your development schema](/reference/node-selection/defer#usage), edit a single model, and run `dbt build -s state:modified` &mdash;  only the edited model runs. Any `{{ ref() }}`<VersionBlock firstVersion="1.11"> and `{{ function() }}`</VersionBlock> calls resolve to the staging or production location of the referenced models<VersionBlock firstVersion="1.11"> and user-defined functions</VersionBlock>.

<Lightbox src="/img/docs/dbt-cloud/defer-toggle.png" width="100%" title="Select the 'Defer to production' toggle on the bottom right of the command bar to enable defer in the Studio IDE."/>

### Defer in dbt CLI

One key difference between using `--defer` in the <Constant name="platform_cli" /> and the <Constant name="studio_ide" /> is that `--defer` is *automatically* enabled in the <Constant name="platform_cli" /> for all invocations, compared with production artifacts. You can disable it with the `--no-defer` flag.

### Configure deferral environment ID

The <Constant name="studio_ide" /> and <Constant name="platform_cli" /> both offer additional flexibility by letting you choose the source environment for deferral artifacts. You can manually set a `defer-env-id` key in either your `dbt_project.yml` (<Constant name="platform_cli" /> and <Constant name="studio_ide" />) or `dbt_cloud.yml`(<Constant name="platform_cli" /> only) file. By default, dbt will prefer metadata from the project's "Staging" environment (if defined). Otherwise, it uses "Production."

<Lightbox src="/img/docs/dbt-cloud/defer-env-id.png" width="100%" title="Set the defer environment and the target name will change in the UI."/>

<File name="dbt_cloud.yml">

```yml
context:
  active-host: ...
  active-project: ...
  defer-env-id: '123456'
```

</File>


<File name="dbt_project.yml"> 

```yml
dbt-cloud:
  defer-env-id: '123456'
```

</File>
