Master the ‘gradlew clean’ Command: What It Deletes

Updated

gradlew clean

Run ./gradlew clean from the folder that holds the gradlew script, which is normally the project root. The gradlew clean command runs Gradle’s clean task, which by default deletes only the project’s build directory, build/.

# macOS and Linux
./gradlew clean

# Windows Command Prompt
gradlew.bat clean

# Windows PowerShell
.\gradlew.bat clean

With a system-wide Gradle install, gradle clean does the same job, but the wrapper is recommended because it uses the version the project declares. Either way, the build cache, the dependency cache, the configuration cache and the Gradle daemons survive it. The table below pairs each goal with the command that does it.

What gradlew clean deletes

The task comes from Gradle’s Base plugin. Its documentation says clean “Deletes the build directory and everything in it, i.e. the path specified by the layout.buildDirectory project property.” The Java plugin applies Base for you. If nothing in the build brings Base in, ./gradlew clean fails with Task 'clean' not found in root project, and plugins { base } in build.gradle.kts (or plugins { id 'base' } in build.gradle) fixes that. ./gradlew tasks lists what a project offers.

Run gradlew.bat clean on Windows

In Command Prompt, gradlew.bat clean works from the project folder. PowerShell does not run a program in the current directory by its bare name, so use .\gradlew.bat clean there. Microsoft’s PowerShell documentation says to give the full path or the .\ prefix, and Android’s command-line docs write ./gradlew for PowerShell.

Run gradlew clean build for a full rebuild

./gradlew clean build runs clean first and build second. The Gradle command-line reference uses this command to show that Gradle respects that order. build depends on check, which holds the verification tasks such as tests, and assemble, which produces the output. The same page warns that cleaning throws away pre-computed outputs and slows the next run, whereas ./gradlew build on its own reuses whatever is still up to date.

When you need gradlew clean and when you don’t

Gradle skips a task whose inputs and outputs have not changed and prints UP-TO-DATE. That is incremental build, and clean throws away the outputs it reuses. I’d run clean only for a reason I can name, such as a release artifact built from an empty directory or stale generated files I can see in build/. If a build is correct only after clean, I’d suspect a task that declares its inputs or outputs wrongly. After a Gradle upgrade you can skip it for compiled classes: Gradle removes stale Java, Groovy and Scala compile output itself, though its docs say that clean-up covers only source-set output.

What gradlew clean leaves alone

The locations are the defaults from Gradle’s directory and cache documentation, and ~/.gradle is C:\Users\<name>\.gradle on Windows.

Goal Command Related location
Delete build output ./gradlew clean build/ in each project
Ignore up-to-date checks ./gradlew build --rerun-tasks None; nothing is deleted
Skip the build cache ./gradlew build --no-build-cache ~/.gradle/caches/build-cache-1; off unless you enable it
Re-check cached dependencies ./gradlew build --refresh-dependencies ~/.gradle/caches/modules-2
Skip the configuration cache ./gradlew build --no-configuration-cache .gradle/configuration-cache in the project root; off unless you enable it
Stop the daemons ./gradlew --stop Daemon processes started by the same Gradle version

The build cache is off by default. Turn it on with --build-cache for one run or org.gradle.caching=true in gradle.properties, and clean still leaves its entries alone. Gradle’s build cache documentation shows ./gradlew clean followed by ./gradlew --build-cache assemble printing :compileJava FROM-CACHE, and I got the same on Gradle 9.8.0. There, adding --rerun-tasks or --no-build-cache made compileJava run again. The docs only say --rerun-tasks ignores up-to-date checks, so with the cache on, pass both: ./gradlew build --rerun-tasks --no-build-cache.

--refresh-dependencies is for dependency problems, such as a repository that was misconfigured at first or a module that was published wrongly. It tells Gradle to ignore cached entries for resolved modules and artifacts and resolve them again, but it re-downloads only what changed, because Gradle compares checksums.

The configuration cache is off by default too, and Gradle’s docs say it becomes the default in Gradle 10. When it is on, Gradle invalidates it by itself when build scripts or other configuration inputs change, so clean is not the fix. If you suspect an input Gradle does not track, delete .gradle/configuration-cache. I confirmed that clean leaves that directory in place.

./gradlew --stop ends every daemon started by the same Gradle version. Gradle’s docs suggest it when builds behave unexpectedly, and the next build starts a fresh daemon.

Android: Gradle clean vs Android Studio’s Rebuild Project

Android’s command-line docs run the wrapper from the project root. Each module has its own build directory, and a debug APK is written under <module>/build/outputs/apk/. From the root, ./gradlew clean runs in every module that has the task, and ./gradlew :app:clean limits it to the module named app. ./gradlew clean assembleDebug gives a clean debug build in one command.

Android Studio builds with Gradle too, and View > Tool Windows > Build lists the tasks it ran. Since Android Studio Meerkat | 2024.3.1, the old Rebuild Project action is called Clean and Assemble Project with Tests, and Make Project is called Assemble Project, according to the release notes. The new name spells out what Rebuild does: a clean, then an assemble that includes the test components.

Fix ./gradlew: Permission denied

The script is there but its execute bit is missing. chmod +x gradlew sets it:

$ ./gradlew clean
bash: ./gradlew: Permission denied

$ chmod +x gradlew
$ ./gradlew clean

zsh, the macOS default, prints zsh: permission denied: ./gradlew. If the project is in Git, record the executable bit so teammates and CI do not hit the same error: run git update-index --chmod=+x gradlew, then commit.

Leaving off the ./ gives a different error, bash: gradlew: command not found or zsh: command not found: gradlew. Bash searches PATH only for names that contain no slash, and the current directory is not normally on PATH.

Which Gradle version is current

Gradle 9 is the current major version, and 9.8.0 was the latest release on 1 October 2026. Gradle 10 has not been released. curl -s https://services.gradle.org/versions/current prints the latest release at any time, and ./gradlew --version prints the version your project uses. To move to 9.8.0, run ./gradlew :wrapper --gradle-version 9.8.0 and then ./gradlew :wrapper once more, which refreshes the wrapper JAR and scripts as well as gradle-wrapper.properties.

Photo of author
Sudhir P. founded HeatWare.com in 1999 and has built and operated it full-stack ever since; it is now used by more than 88,000 people. He writes here about the PostgreSQL, MySQL, Linux and DevOps work that keeps it running. Articles are rewritten only after the commands in them have actually been run, and the verification scripts are published alongside them so anyone can check the claims. Reach him at blog@heatware.net.