Gradlew Not Found | Fix It In Minutes

Guide / By

The Gradle Wrapper script issue usually means the gradlew file is missing, not executable, or you’re in the wrong folder.

You run a build and your terminal throws the same error again. If you’re seeing gradlew not found, the project usually isn’t broken. The wrapper script is. Fix the wrapper, and the build comes back to life.

If you work in Android Studio, check the Gradle tool window too; it often shows the folder and command it ran.

This article walks you through the checks that solve the problem on macOS, Linux, Windows, and CI. You’ll also see how to prevent the issue from showing up on the next clone or pipeline run at all.

What The Gradle Wrapper Does

The Gradle Wrapper is the recommended way to run a Gradle build. It’s a pair of scripts, gradlew for Unix-like systems and gradlew.bat for Windows, that run the exact Gradle version the project expects. If the right Gradle version isn’t present, the wrapper downloads it and then runs the build. That keeps local machines and CI aligned without asking every contributor to install the same Gradle release.

When the wrapper is set up, your project root has these basics:

  • Spot The Scripts — A gradlew file (macOS/Linux) and a gradlew.bat file (Windows) in the project root.
  • Check The Wrapper Folder — A gradle/wrapper/ directory with gradle-wrapper.properties and the wrapper JAR.
  • Run With A Relative Path — On macOS/Linux you typically run ./gradlew, not gradlew, unless your shell PATH includes the current folder.

So the “not found” message is rarely about Gradle itself. It’s about one of these: the file is missing, you aren’t in the right directory, the script can’t be executed, or Git checked it out in a way that drops the execute bit.

Gradlew Not Found On Mac And Linux With Fast Checks

On macOS and Linux, most cases fall into three buckets: wrong folder, missing file, or missing execute permission. Start with the fastest checks first, then move down the list until the command runs.

Confirm You’re In The Project Root

The wrapper scripts live in the top-level folder of the project. If you run ./gradlew from inside app/, android/, or another subfolder, your shell won’t find it.

  1. Print Your Location — Run pwd and confirm the folder is the same one that contains settings.gradle or settings.gradle.kts.
  2. List The Files — Run ls and look for gradlew at the top level.
  3. Run The Local Script — Use ./gradlew tasks to confirm the wrapper launches and the project is readable.

Use The Right Command Form

Many shells don’t search the current folder by default. That means typing gradlew can fail even when the file exists. The wrapper is meant to be run by path, like ./gradlew on macOS/Linux.

  • Run It Directly — Use ./gradlew build or ./gradlew test.
  • Check For A Hidden Extension — If the file is named gradlew.txt by mistake, rename it back to gradlew.
  • Watch For Case — On many systems, Gradlew and gradlew are different names.

Fix Permissions When The File Exists

If the script is present yet won’t execute, the fix is usually one command. Git can also drop the execute flag if the repo was prepared on Windows and checked out on Linux or macOS.

  1. Check The Mode — Run ls -l gradlew. If you don’t see an x in the permissions, it’s not executable.
  2. Grant Execute Permission — Run chmod +x gradlew, then try ./gradlew --version.
  3. Commit The Fix — If you own the repo, set the bit in Git and commit it so teammates and CI don’t repeat the same step.

That last step matters. Some teams fix it locally and stop, then the next fresh clone fails again. A common Git approach is to stage the permission change and commit it so the file keeps its executable state across clones.

Quick Cause Map

If you want a fast match between the message you see and the next action, this table helps.

What You See Most Likely Cause Next Check
gradlew: command not found Not in PATH or wrong folder Run ./gradlew from project root
No such file or directory Wrapper script missing Generate wrapper files
Permission denied Execute bit missing chmod +x gradlew

Fix The Wrapper On Windows And PowerShell

On Windows, the wrapper entry point is usually gradlew.bat. Many editors and IDEs call it for you, so the issue often appears when you switch to PowerShell, Command Prompt, or a CI runner that uses Windows images.

Run The Batch Script From The Root

  1. Open The Right Folder — In File Manager, open the folder that contains gradlew.bat.
  2. Start A Shell There — Shift-right-click and open a terminal in that folder.
  3. Run The Wrapper — Use gradlew.bat tasks in Command Prompt, or ./gradlew.bat tasks in PowerShell.

Watch For Line Endings And Zip Downloads

If the project was downloaded as a ZIP and unpacked with a tool that rewrites files, scripts can get damaged or renamed. Git clones are safer for wrapper scripts. If you must use a ZIP, verify that both wrapper scripts exist and that gradle/wrapper/gradle-wrapper.properties is present.

When The Wrapper Files Are Missing

Sometimes the script is not there at all. That’s common in new repos that forgot to commit wrapper files, projects that were copied from another folder, or builds that rely on a system Gradle install and never created a wrapper.

Your goal is to (1) generate the wrapper once, (2) commit the wrapper scripts and the wrapper folder, and (3) use the wrapper for builds from now. Gradle’s documentation describes the wrapper as the recommended way to execute builds for consistent results.

  1. Check For A System Gradle Install — Run gradle --version. If the command exists, you can use it to create the wrapper.
  2. Create The Wrapper — From the project root, run gradle wrapper. This generates gradlew, gradlew.bat, and the gradle/wrapper/ files.
  3. Commit The Output — Add the scripts and gradle/wrapper/ to version control so every clone can build the same way.

If you don’t have system Gradle installed and you can’t run gradle wrapper, you have two practical paths. Install Gradle once on your machine just long enough to run the wrapper task, or copy the wrapper files from a known-good branch or tag of the same project. The wrapper exists to remove repeated setup, yet it does need to be created at least once.

Check The Wrapper Properties For The Right URL

After wrapper generation, open gradle/wrapper/gradle-wrapper.properties and confirm it points to a valid Gradle distribution. If the distribution URL is broken, the wrapper script can run yet fail when it tries to download Gradle. Keeping the wrapper properties up to date is part of normal Gradle maintenance.

Cases Where It Exists But Still Won’t Run

This is the spot where teams lose time, because the file is present and everyone assumes it should work. The fixes below target the most common traps: line ending issues, wrong working directory in CI, and repo settings that strip executable bits.

Run From A CI Working Directory That Matches The Repo Root

CI systems often set a working directory that is not the repo root, especially in monorepos. If the pipeline runs in a subfolder, ./gradlew won’t exist at that path.

  1. Print The Directory — Add a step that runs pwd (or cd on Windows) before invoking Gradle.
  2. List The Folder — Add ls to confirm gradlew is present at that location.
  3. Adjust The Step — Either change the working directory to the repo root or call the wrapper by its relative path, like ../gradlew.

Repair The Executable Bit In Git Once, Not Every Build

Adding chmod +x gradlew in a CI job works, yet it can be a smell. It often means the repo never stored the executable flag. Set it once and commit it so that Linux runners can execute it on every clone without extra steps. Discussions across CI platforms often land on the same fix: mark gradlew as executable in Git.

Spot A Windows Checkout That Breaks The Script

If a Linux runner reports /usr/bin/env: ‘sh\r’: No such file or directory or similar, the script has Windows line endings. Fix it by setting your repo to keep Unix endings for gradlew, then recommit the corrected file.

  • Convert The File — Use dos2unix gradlew or configure your editor to save with LF endings.
  • Set Git Attributes — Add a rule that forces LF endings for shell scripts so new commits stay clean.
  • Re-Check Permissions — After conversion, confirm chmod +x still applies.

Make The Wrapper Stop Failing On New Clones

Once you’ve fixed the immediate error, lock in a setup that keeps the wrapper reliable for every developer machine and build runner. The wrapper is built for repeatable builds across systems, so treat it as part of the build product, not an optional extra.

Commit The Full Wrapper Set

A minimal wrapper commit includes gradlew, gradlew.bat, and the entire gradle/wrapper/ directory. Avoid committing your local Gradle cache. Stick to the wrapper files the build needs.

  • Keep The Scripts — Add both wrapper scripts so Windows and Unix machines can build.
  • Keep The Properties — The properties file pins the Gradle distribution version and URL.
  • Verify The Wrapper JAR — Teams that care about supply-chain safety can also verify wrapper integrity using Gradle’s wrapper checks.

Use One Reliable Build Command In Docs

Pick one command for your README and internal docs and stick with it. On macOS/Linux, use ./gradlew build. On Windows, use gradlew.bat build. When docs say “run gradle build,” new contributors install random Gradle versions and bugs appear that no one else can reproduce.

Add A Small Preflight Step In CI

A tiny preflight step can save hours of log digging.

  1. Print Context — Log the working directory and list the root folder.
  2. Check Wrapper Presence — Fail early if gradlew or gradle/wrapper/ is missing.
  3. Run A Light Task — Use ./gradlew --version or ./gradlew tasks before heavier tasks so wrapper issues surface fast.

If you still hit the error after these steps, re-check the basics: correct folder, correct script name, correct execute permission, and wrapper files committed. Most cases reduce to one of those four. Articles focused on the wrapper tend to list the same core fixes: generate missing wrapper files, fix permissions, and run the script from the right location.

Once your wrapper is in place, the next time you see the message gradlew not found, you’ll know where to look, and you’ll fix it in a few commands instead of a full reset.