dbt clean Command: When and Why to Clear Compiled Artifacts

dbt clean is the smallest and least dramatic command in dbt’s CLI, and that’s exactly why it’s worth understanding precisely — it’s tempting to reach for it as a generic “fix weird behavior” reset button, but it only does one specific, narrow thing, and knowing what it doesn’t do saves time chasing the wrong fix.

What dbt clean Actually Deletes

dbt clean

By default, this deletes the directories listed under clean-targets in dbt_project.yml — almost always target/ (compiled SQL, run artifacts) and dbt_packages/ (installed package dependencies).

clean-targets:
  - "target"
  - "dbt_packages"

That’s the entire scope. It does not touch anything in your actual warehouse — no tables are dropped, no data is deleted. It’s purely a local filesystem cleanup of generated/downloaded artifacts.

Why This Command Exists at All

Two categories of problem it genuinely solves:

Stale compiled SQL causing confusing debugging. If you’re inspecting target/compiled/ to debug a Jinja issue (the technique covered throughout this series, including in Jinja Templating) and suspect you’re looking at an old compilation rather than the current one, clearing target/ and recompiling guarantees you’re looking at fresh output.

Package installation issues. If dbt_packages/ gets into a corrupted or partially-downloaded state — an interrupted dbt deps run, a version conflict that didn’t resolve cleanly — clearing it and reinstalling from scratch is often faster than debugging the partial state.

dbt clean
dbt deps
dbt compile

What dbt clean Does Not Fix

It’s a common but incorrect assumption that dbt clean resets warehouse state, fixes a broken model, or clears cached query results in the warehouse itself. None of that is in scope:

Reaching for dbt clean when the actual problem is in your SQL logic or warehouse state wastes time without addressing anything.

Customizing clean-targets

Some projects generate additional local artifacts worth including in the cleanup scope — a custom docs output directory, for instance.

clean-targets:
  - "target"
  - "dbt_packages"
  - "logs"

Be deliberate about what’s added here — accidentally including a directory that contains something you didn’t mean to delete (a manually maintained local config, for instance) turns a routine cleanup into an unpleasant surprise.

dbt clean in CI Pipelines

Some CI configurations run dbt clean at the start of every job as a defensive habit, ensuring no artifacts persist between runs on a shared runner.

# Example CI step
- run: dbt clean
- run: dbt deps
- run: dbt build

On ephemeral CI runners that start from a fresh filesystem every time, this is usually unnecessary — there’s nothing stale to clean. It matters more on long-lived, shared build agents where artifacts from a previous, different branch’s run could otherwise persist and cause confusing cross-contamination between jobs.

A Realistic Scenario Where dbt clean Actually Helps

Consider switching between two feature branches locally, one that installed a newer version of dbt_utils and one still pinned to an older version. If dbt_packages/ isn’t reinstalled cleanly between the switch, you can end up with a mismatched or partially-overwritten package directory that doesn’t match either branch’s packages.yml exactly — commands might still run, but macro behavior can be inconsistent with what either branch actually declares.

git checkout other-feature-branch
dbt clean
dbt deps
dbt compile

This sequence guarantees the installed packages exactly match the currently checked-out branch’s declared versions, eliminating an entire category of “why is this macro behaving differently than I expect” confusion that stems from a stale, partially-mismatched local package cache rather than any actual bug in your project.

Why It’s Rarely Needed Day-to-Day

For most local development, dbt regenerates target/ fresh on every run, compile, or test invocation anyway — you don’t need to manually clear it first for a normal compile to reflect your latest changes. The command exists for the specific edge cases above, not as a routine step in an ordinary workflow.

Common Mistakes

Running it reflexively when debugging any dbt issue. Since it only affects local artifacts, it does nothing for the much more common category of problems — broken SQL logic, misconfigured sources, incorrect warehouse permissions.

Adding directories to clean-targets without checking what’s actually there. A misconfigured clean-targets list can delete something genuinely useful that happened to be created in the same directory dbt expects to be disposable.

Forgetting dbt deps is needed after cleaning dbt_packages/. dbt clean removes installed packages; it doesn’t reinstall them — a dbt deps run afterward is required before any command that depends on package macros will work again.

Summary

dbt clean is a narrow, purely local housekeeping command — useful in the specific situations it’s designed for, and a waste of time as a generic troubleshooting reflex for anything happening in the actual warehouse.