How to Fix the gradlew: command not found Error in Linux

1. Overview

Gradle is a popular build automation tool. It’s used in many projects built on Java, Kotlin, and Android. Often, these projects use a script named gradlew. This file is also known as the Gradle Wrapper. The purpose of the wrapper file is to ensure that a project uses a specific Gradle version, even when different systems have different Gradle installations.

In this tutorial, we’ll explore a common Gradle error: ./gradlew: command not found. Specifically, we’ll try to understand the causes of the error. In addition, we’ll see how to reproduce and fix this error.

2. Understanding the Problem

Gradle can work in two ways:

1. run using a system-wide installation
2. run using the project-specific Gradle Wrapper script (gradlew on Linux)

If we already have a Gradle project, we don’t need to install Gradle, as we can use a project-specific Gradle Wrapper. In this case, the wrapper uses the Gradle version from the gradle/wrapper/gradle-wrapper.properties configuration file.

However, in Linux systems, we might see an error when running the ./gradlew command:

$ ./gradlew
bash: ./gradlew: command not found

The above issue may appear for several reasons:

• file missing in the cloned or local code repositories
• file not executable
• running the file from the incorrect path
• others

Notably, all actions here were performed by installing Gradle using both the package manager and the manual installation process. In both cases, the following steps should be applicable.

3. Steps to Reproduce the Error

Let’s first understand how the gradlew: command not found error appears in a typical Linux environment.

Here, we want to confirm two facts:

1. root cause of the error
2. system-wide Gradle installation isn’t necessary

So, let’s examine cases where this error may occur.

To start with, we create a sample project, gradle-demo:

$ mkdir gradle-demo && cd gradle-demo

Next, we initiate the project as a Java application:

$ gradle init --type java-application

Eventually, we get a working Gradle project.

Let’s see the content of the project directory:

$ ls
build.gradle gradle gradlew gradlew.bat settings.gradle src

From the output, let’s check the permission set for the file gradlew:

$ ls -l gradlew
-rwxrwxr-x 1 vagrant vagrant 8618 Nov 10 06:12 gradlew

Next, we run the gradlew command:

$ gradlew
-bash: gradlew: command not found

Thus, we can see the issue at hand.

4. Diagnosing and Fixing the Cause

Now that we’ve reproduced the error, let’s see the steps to identify and fix any related issues.

4.1. Running gradlew Without ./ or a Path

On a Linux system, if we run any script directly only via its name, we can get the command not found error:

$ gradlew
-bash: gradlew: command not found

If we intend to use the script by its name, we can put it in a place where the shell usually checks for executables, such as /usr/local/bin, /bin, and similar.

Alternatively, we can move the script to one of the directories pointed to by the PATH environment variable or add the current script directory path to that list. Notably, we might need to configure the ~/.bashrc or ~/.bash_profile files for the changes.

However, if we don’t want to make many changes, we can just explicitly reference the script with ./ as long as we’re currently in the script’s directory:

$ ./gradlew

The ./ prefix tells the shell to execute the file named gradlew located in the current directory.

Alternatively, we can specify the full absolute path (usually the project root) and run it that way:

$ /full/path/to/gradlew

This should work the same way.

4.2. Fixing File Permissions

Sometimes, when running a script correctly, we may encounter issues related to file permissions. Specifically, a script file might simply not have the execution permission.

In this case, we have two options:

1. use a specific shell to run the script
2. set the script to be executable on its own

Naturally, we should be able to use bash to run gradlew directly, as long as it’s in the current directory or we know its full path:

$ bash gradlew

On the other hand, we can just give the file execution permission:

$ sudo chmod +x gradlew

Now, the script should execute normally when called directly:

$ ./gradlew

Again, we can use the script name gradlew directly if the current directory is properly set.

4.3. Fixing the Missing File Issue

Often, developers store the wrapper files inside the same repository as the rest of the code. However, in some repositories, these files might be missing. In other words, a wrapper file like gradlew might not be included in the cloned project.

So, we check whether the files related to the Gradle wrapper are present:

$ ls -l

Next, if the files are missing, we can generate them using the gradle command:

$ gradle wrapper

The above command restores the necessary files related to Gradle Wrapper, including gradlew.

4.4. Working Directory Issue

In Gradle, the gradlew file should reside at the root directory of a project.

If the file is located elsewhere, we move it to the root of the project:

$ cp /current/path/to/gradlew /path/to/project/gradlew
$ cd /path/to/project
$ ./gradlew

As a result, the above approach should resolve the path-related issues. Notably, care should be taken that the correct file is copied to the proper location.

5. Conclusion

In this article, we discussed reasons for the gradlew: command not found error. To summarize, the fix for this error mainly revolves around three solutions:

• generating the wrapper files (if missing)
• fixing file permissions
• placing the file at the correct location (root directory)

Often, the above error is resolved with correct execute permission.