# Gradle Wrapper Basics

version 8.12

The recommended way to execute any Gradle build is with the Gradle Wrapper.

The Wrapper script invokes a declared version of Gradle, downloading it beforehand if necessary.

The Wrapper is available as a `gradlew` or `gradlew.bat` file.

The Wrapper provides the following benefits:

- Standardizes a project on a given Gradle version.

- Provisions the same Gradle version for different users.

- Provisions the Gradle version for different execution environments (IDEs, CI servers…​).

## Using the Gradle Wrapper

It is always recommended to execute a build with the Wrapper to ensure a reliable, controlled, and standardized execution of the build.

Depending on the operating system, you run `gradlew` or `gradlew.bat` instead of the `gradle` command.

Typical Gradle invocation:

    $ gradle build

To run the Wrapper on a Linux or OSX machine:

    $ ./gradlew build

To run the Wrapper on Windows PowerShell:

    $ .\gradlew.bat build

The command is run in the same directory that the Wrapper is located in. If you want to run the command in a different directory, you must provide the relative path to the Wrapper:

    $ ../gradlew build

The following console output demonstrates the use of the Wrapper on a Windows machine, in the command prompt (cmd), for a Java-based project:

    $ gradlew.bat build

    Downloading https://services.gradle.org/distributions/gradle-5.0-all.zip
    .....................................................................................
    Unzipping C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-all\ac27o8rbd0ic8ih41or9l32mv\gradle-5.0-all.zip to C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-al\ac27o8rbd0ic8ih41or9l32mv
    Set executable permissions for: C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-all\ac27o8rbd0ic8ih41or9l32mv\gradle-5.0\bin\gradle

    BUILD SUCCESSFUL in 12s
    1 actionable task: 1 executed

## Understanding the Wrapper files

The following files are part of the Gradle Wrapper:

    .
    ├── gradle
    │   └── wrapper
    │       ├── gradle-wrapper.jar  (1)
    │       └── gradle-wrapper.properties   (2)
    ├── gradlew (3)
    └── gradlew.bat (4)

1 | `gradle-wrapper.jar`: This is a small JAR file that contains the Gradle Wrapper code. It is responsible for downloading and installing the correct version of Gradle for a project if it’s not already installed.
2 | `gradle-wrapper.properties`: This file contains configuration properties for the Gradle Wrapper, such as the distribution URL (where to download Gradle from) and the distribution type (ZIP or TARBALL).
3 | `gradlew`: This is a shell script (Unix-based systems) that acts as a wrapper around `gradle-wrapper.jar`. It is used to execute Gradle tasks on Unix-based systems without needing to manually install Gradle.
4 | `gradlew.bat`: This is a batch script (Windows) that serves the same purpose as `gradlew` but is used on Windows systems.

| You should never alter these files.

If you want to view or update the Gradle version of your project, use the command line. Do not edit the wrapper files manually:

    $ ./gradlew --version
    $ ./gradlew wrapper --gradle-version 7.2

    $ gradlew.bat --version
    $ gradlew.bat wrapper --gradle-version 7.2

Consult the Gradle Wrapper reference to learn more.

Next Step: Learn about the Gradle CLI >>