Analysis and Solutions for 'gradlew: command not found' Error

Problem Background and Phenomenon Analysis

When using Gradle to build Java projects, developers often encounter the gradlew: command not found error message. This typically occurs in Linux or macOS systems when users attempt to execute commands like gradlew clean jpackage, and the system cannot recognize the gradlew command.

From a technical perspective, the core reason for this error lies in the Gradle Wrapper script not being properly generated or configured. Gradle Wrapper is a standalone script file responsible for downloading specified versions of Gradle and executing build tasks without requiring users to pre-install Gradle at the system level.

Working Principle of Gradle Wrapper

Gradle Wrapper consists of three core files: gradlew (Unix/Linux script), gradlew.bat (Windows batch file), and gradle/wrapper/gradle-wrapper.jar. When executing the ./gradlew command, the Wrapper script checks if the required version of Gradle is available locally. If not, it automatically downloads it from the official Gradle repository.

Unlike directly installing system-level Gradle, Wrapper provides version isolation and environment consistency guarantees. Each project can use a specific version of Gradle, avoiding build issues caused by different system Gradle versions.

Main Solutions

Generating Gradle Wrapper

If the Wrapper files are missing from the project, they need to be generated first. Use the installed system Gradle to execute the following command:

gradle wrapper --gradle-version 7.6

The version number 7.6 should be replaced with the specific Gradle version required by the project. After successful execution, the gradlew script file and gradle/wrapper/ directory structure will be generated in the project directory.

Setting Execution Permissions

In Unix-like systems, newly generated script files do not have execution permissions by default. Run:

chmod +x gradlew

Or use more restrictive permission settings:

chmod 755 gradlew

Permission issues frequently occur in cross-platform development, especially when copying files from Windows systems to Linux environments.

Correct Command Execution

Since gradlew is not in the system's PATH environment variable, it must be executed using relative or absolute paths:

./gradlew clean build

The corresponding command in Windows PowerShell is:

.\gradlew clean build

Environment Variables and Proxy Configuration

In some enterprise environments, proxy configuration may be necessary. The referenced article demonstrates how improper environment variable configuration can cause Wrapper execution failures.

When setting the GRADLE_OPTS environment variable, special attention should be paid to special character handling. For example:

export GRADLE_OPTS="-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=3128 -Dhttps.nonProxyHosts=*.example.com"

If using pipe characters | to separate multiple domains, ensure proper escaping to prevent shell misinterpretation.

Troubleshooting Steps

1. Check if the gradlew file exists in the project root directory
2. Verify file permissions: ls -l gradlew should display -rwxr-xr-x
3. Confirm Java environment: java -version should show the correct JDK version
4. Check network connectivity to ensure access to Gradle distribution servers
5. Review Wrapper configuration: check the gradle/wrapper/gradle-wrapper.properties file

Best Practice Recommendations

To ensure project portability and build consistency, it is recommended to:

• Always use Gradle Wrapper instead of system-installed Gradle
• Include Wrapper files in version control systems
• Regularly update Wrapper to the latest stable version
• Use Wrapper in CI/CD environments to ensure environment consistency
• Specify clear Gradle version ranges for team projects

By properly configuring and using Gradle Wrapper, developers can avoid environment dependency issues and ensure reliable project builds in any environment.