What does flutter clean delete in a Flutter project, and when does it fix a build rather than just slow the next one?

middleshould knowfreq 48%

answer

project outputs, not the SDK
build/ and .dart_tool/
ephemeral and generated platform files
lock file and Pods survive
precache fills the SDK cache

basics

~20 s

flutter clean deletes the project's build/ and .dart_tool/ directories, platform ephemeral folders and generated files, and cleans the Xcode workspace. It helps when stale generated state survives an SDK, plugin or config change; otherwise it only forces a slower full rebuild.

solid answer

~40 s

flutter clean removes project-level generated state: build/, .dart_tool/, each platform's ephemeral folder, the generated Xcode properties and environment script, the generated Flutter podspec and .flutter-plugins-dependencies, and it runs an Xcode workspace clean when Xcode is installed. It keeps pubspec.lock, your source and the ios/Pods folder, and it does not touch the SDK's artifact cache or the pub cache. It genuinely fixes builds after an SDK upgrade or channel switch, after adding or removing plugins, or when a platform build reads stale generated files. For an ordinary compile error it fixes nothing and costs a full rebuild plus pub get. Its opposite is flutter precache, which downloads engine artifacts into the SDK's bin/cache ahead of time.

`flutter clean` removes **project-level generated state**: `build/`, `.dart_tool/`, each platform's ephemeral folder, the generated Xcode properties and environment script, the generated Flutter podspec and `.flutter-plugins-dependencies`, and it runs an Xcode workspace clean when Xcode is installed. It keeps `pubspec.lock`, your source and the `ios/Pods` folder, and it does not touch the SDK's artifact cache or the pub cache. It genuinely fixes builds after an SDK upgrade or channel switch, after adding or removing plugins, or when a platform build reads stale generated files. For an ordinary compile error it fixes nothing and costs a full rebuild plus `pub get`. Its opposite is `flutter precache`, which downloads engine artifacts into the SDK's `bin/cache` ahead of time.

code

bash · 5 lines

bash

flutter clean                # build/, .dart_tool/, ephemeral + generated files, Xcode workspace
flutter pub get              # optional; the next run or build would do it anyway
flutter run -d emulator-5554

flutter precache --android --ios   # fill the SDK's bin/cache ahead of time

go deeper

for a junior

Know that flutter clean deletes build/ and .dart_tool/ and that the next build is slower because everything is rebuilt.

for a middle

Explain which generated files clean removes and which survive, and the difference between project outputs and the SDK cache that precache fills.

for a senior

Recognise the failures clean actually fixes, stale generated state after SDK or plugin changes, and send others to the right fix: dependencies, Pods or Gradle.

for a principal

Keep clean builds out of the default workflow and CI where they only add time, and precache artifacts in CI images instead.

Two different caches

A Flutter build draws on two kinds of stored state, and the CLI has a command for each:

State	Where it lives	Command
Project build outputs and generated files	inside the project	`flutter clean` deletes them
Engine binaries and tools for each platform	the SDK's `bin/cache`	`flutter precache` downloads them
Downloaded packages	the user's pub cache	neither; that is pub's domain

Keeping these apart avoids the most common misunderstanding: flutter clean never re-downloads the engine and never clears downloaded packages.

What flutter clean deletes

For the project (and, with --include-example, its example/ app):

build/ — compiled outputs for every platform.
.dart_tool/ — the package configuration, build-system state and incremental compiler data.
Ephemeral platform folders — generated folders the tool recreates on each build, for example ios/Flutter/ephemeral and the desktop flutter/ephemeral folders.
Generated iOS files — Generated.xcconfig, flutter_export_environment.sh and the generated Flutter.podspec.
.flutter-plugins-dependencies — the plugin list per platform.
Xcode workspace — when Xcode is installed, it runs a workspace clean for iOS and macOS; --scheme limits this to one scheme.

It does not delete pubspec.lock, ios/Pods, ios/Podfile.lock, Gradle's caches, the pub cache or the SDK's artifacts. After cleaning, the next flutter run or flutter build runs pub get again and rebuilds everything from scratch.

When it helps

It fixes problems whose cause is generated state that no longer matches its inputs:

After an SDK upgrade or channel switch — .dart_tool and build/ hold artifacts compiled by the previous engine.
After adding, removing or changing plugins — the plugin list and generated platform files can lag.
Moved or renamed projects — generated files may contain absolute paths to the old location.
Xcode build errors that mention generated Flutter files — the regenerated Generated.xcconfig and podspec resolve them.

When it does not

A Dart compile or analysis error — the source is wrong; cleaning rebuilds the same error slower.
Dependency conflicts — those come from pubspec.yaml constraints and resolution.
CocoaPods problems — ios/Pods and Podfile.lock survive a clean; the fix is in the Pods workflow.
Gradle or JDK mismatches — Gradle's own caches and wrapper are outside the project folders clean touches.

The habit of running flutter clean before every build wastes minutes each time. Use it as a targeted reset, then rebuild once.

flutter precache

flutter precache populates the SDK's artifact cache. With no platform flags it downloads artifacts for every platform enabled on the current host; flags such as --android, --ios, --web narrow it, --all-platforms fetches every host's, and --force re-downloads. Uses:

warming a CI image or container so builds do not download engines at run time;
preparing a laptop before working offline.

Switching channels already precaches by default, and flutter upgrade precaches as part of its work.

A decision checklist

Before running flutter clean, ask:

Did the SDK, a plugin, or a platform setting change since the last good build? If yes, clean is a reasonable first step.
Does the error name a generated file (Generated.xcconfig, the plugin list, a file under ephemeral)? If yes, clean regenerates it.
Is the error in my own Dart, Gradle or Pods configuration? If yes, clean will not help; fix the source.

## Two different caches A Flutter build draws on two kinds of stored state, and the CLI has a command for each: | State | Where it lives | Command | |---|---|---| | Project build outputs and generated files | inside the project | `flutter clean` deletes them | | Engine binaries and tools for each platform | the SDK's `bin/cache` | `flutter precache` downloads them | | Downloaded packages | the user's pub cache | neither; that is pub's domain | Keeping these apart avoids the most common misunderstanding: `flutter clean` never re-downloads the engine and never clears downloaded packages. ## What flutter clean deletes For the project (and, with `--include-example`, its `example/` app): - **`build/`** — compiled outputs for every platform. - **`.dart_tool/`** — the package configuration, build-system state and incremental compiler data. - **Ephemeral platform folders** — generated folders the tool recreates on each build, for example `ios/Flutter/ephemeral` and the desktop `flutter/ephemeral` folders. - **Generated iOS files** — `Generated.xcconfig`, `flutter_export_environment.sh` and the generated `Flutter.podspec`. - **`.flutter-plugins-dependencies`** — the plugin list per platform. - **Xcode workspace** — when Xcode is installed, it runs a workspace clean for iOS and macOS; `--scheme` limits this to one scheme. It does **not** delete `pubspec.lock`, `ios/Pods`, `ios/Podfile.lock`, Gradle's caches, the pub cache or the SDK's artifacts. After cleaning, the next `flutter run` or `flutter build` runs `pub get` again and rebuilds everything from scratch. ## When it helps It fixes problems whose cause is **generated state that no longer matches its inputs**: 1. **After an SDK upgrade or channel switch** — `.dart_tool` and `build/` hold artifacts compiled by the previous engine. 2. **After adding, removing or changing plugins** — the plugin list and generated platform files can lag. 3. **Moved or renamed projects** — generated files may contain absolute paths to the old location. 4. **Xcode build errors that mention generated Flutter files** — the regenerated `Generated.xcconfig` and podspec resolve them. ## When it does not - **A Dart compile or analysis error** — the source is wrong; cleaning rebuilds the same error slower. - **Dependency conflicts** — those come from `pubspec.yaml` constraints and resolution. - **CocoaPods problems** — `ios/Pods` and `Podfile.lock` survive a clean; the fix is in the Pods workflow. - **Gradle or JDK mismatches** — Gradle's own caches and wrapper are outside the project folders `clean` touches. The habit of running `flutter clean` before every build wastes minutes each time. Use it as a targeted reset, then rebuild once. ## flutter precache `flutter precache` populates the SDK's artifact cache. With no platform flags it downloads artifacts for every platform enabled on the current host; flags such as `--android`, `--ios`, `--web` narrow it, `--all-platforms` fetches every host's, and `--force` re-downloads. Uses: - warming a CI image or container so builds do not download engines at run time; - preparing a laptop before working offline. Switching channels already precaches by default, and `flutter upgrade` precaches as part of its work. ## A decision checklist Before running `flutter clean`, ask: 1. Did the SDK, a plugin, or a platform setting change since the last good build? If yes, clean is a reasonable first step. 2. Does the error name a generated file (`Generated.xcconfig`, the plugin list, a file under `ephemeral`)? If yes, clean regenerates it. 3. Is the error in my own Dart, Gradle or Pods configuration? If yes, clean will not help; fix the source.

After flutter clean, an iOS build still fails in CocoaPods. Why didn't clean help?
`flutter clean` deletes Flutter's generated iOS files and runs an Xcode workspace clean, but it leaves `ios/Pods` and `Podfile.lock` in place. A CocoaPods resolution or version problem lives there, so it needs the Pods workflow, not another clean.
Does flutter clean clear the pub cache or re-download the engine?
Neither. It removes only project-level outputs. Downloaded packages stay in the user's pub cache and engine artifacts stay in the SDK's `bin/cache`. `flutter precache --force` re-downloads artifacts; the pub cache is managed by pub.

flutter clean is clearing a workbench of offcuts and jigs made for the last job; it helps when those jigs no longer fit the new job, but it does nothing for a design mistake in the plans.

saying these in an interview costs you the question

Runs flutter clean before every single build
Expects flutter clean to delete pubspec.lock
Thinks flutter clean re-downloads the Flutter engine
Uses flutter clean to fix a Dart compile error
Believes flutter clean empties the pub cache

What does flutter clean delete in a Flutter project, and when does it fix a build rather than just slow the next one?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~3 min

Two different caches

What flutter clean deletes

When it helps

When it does not

flutter precache

A decision checklist

▾common follow-ups2 questions

▾analogy~20 s

▾red flags5 flags

Two different caches

What flutter clean deletes

When it helps

When it does not

flutter precache

A decision checklist

answer

go deeper