Running the Gradle build command builds your Gradle project, including assembling your application and running tests. Discover all the ways to run the Gradle build command, how it works, as well as why it might sometimes be best not to run it.

How to run the Gradle build command

Simply put, to build your application run the following command at your Windows command prompt.

gradlew build

Or if you’re working in a Linux/Mac environment, it’s this.

./gradlew build

What we’re actually doing here is running the Gradle wrapper script and passing it a task name of build.

A Gradle task is an action that can be executed in your build to achieve some outcome. In the case of Java projects, applying the Java plugin automatically adds the build task which assembles and tests your application.

If your project doesn’t have a wrapper script, I recommend adding one immediately by following this Gradle wrapper guide. Alternatively, you can run this command.

gradle build

This relies on you having a Gradle distribution installed locally, and it being a version compatible with your Gradle project and build script.

Build command output

When you run the build command you’ll see output like this.

$ ./gradlew build

4 actionable tasks: 4 up-to-date

This means that your application was assembled and any tests passed successfully.

Gradle creates a build directory, in which it adds these useful outputs.

  1. classes directory: contains compiled .class files, as a result of running the Java compiler against your application Java source files.
  2. libs directory: contains a generated jar file, an archive with all your compiled classes inside ready to be executed or published.
  3. reports directory: contains an HTML report summarising your test results. If your build fails, then consult this report to see what went wrong.

Build command failure

If the build command fails, then the output looks like this.

$ ./gradlew build

> Task :test FAILED

com.tomgregory.GradleTutorialTest > verifyNoExceptionThrown FAILED
    java.lang.RuntimeException at

1 test completed, 1 failed

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':test'.
> There were failing tests. See the report at: file:///C:/workspace/gradle-tutorial/build/reports/tests/test/index.html

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Get more help at

4 actionable tasks: 1 executed, 3 up-to-date

Whatever caused the failure will be shown in the output. In this case it’s a failing test case, so consulting the test report at build/reports/tests/test/index.html would be the next logical step.

How the Gradle build command works

As mentioned earlier, running the build command is more accurately described as running the Gradle wrapper with the build task. When you do this, Gradle reads your build configuration and creates an in memory model of all the tasks that make up your project.

If you’ve applied the Java plugin, Gradle sees that executing the build task actually consists of running several other dependent tasks. These dependent tasks may also depend on other tasks, creating the following task graph.

+--- :assemble
|    `--- :jar
|         `--- :classes
|              +--- :compileJava
|              `--- :processResources
`--- :check
     `--- :test
          +--- :classes
          |    +--- :compileJava
          |    `--- :processResources
          `--- :testClasses
               +--- :compileTestJava
               |    `--- :classes
               |         +--- :compileJava
               |         `--- :processResources
               `--- :processTestResources

Remembering every detail of the task graph isn’t important, but notice that running the build task also runs the assemble and check tasks, and so on. In fact, build is the top level task which runs all other Java-related tasks.

When not to use the Gradle build command

Given the above task tree, it may not always make sense to run the build task. Using the specific dependent task may provide faster results depending on your workflow.

  • If you made a non-test code change and just need to recompile classes and build the jar file, then run the assemble task. This avoids running tests, potentially saving time.
  • If you just need to compile without building the jar file, then run the classes task.

Of course, any savings made will depend on your specific project, but it’s a good idea to be aware that these options exist.

You can see more details about these tasks, including their description, by running the tasks task (./gradlew tasks) and looking under Build tasks and Verification tasks.

Build tasks
assemble - Assembles the outputs of this project.
build - Assembles and tests this project.
buildDependents - Assembles and tests this project and all projects that depend on it.
buildNeeded - Assembles and tests this project and all projects it depends on.
classes - Assembles main classes.
clean - Deletes the build directory.
jar - Assembles a jar archive containing the main classes.
testClasses - Assembles test classes.
Verification tasks
check - Runs all checks.
test - Runs the unit tests.

Final thoughts

You now know that running the Gradle build command is equivalent to running the build task, which you do in Windows with gradlew build and on Linux/Mac with ./gradlew build. The build task depends on other tasks, and in some situations it may make sense to run a more specific task.

To learn more about these fundamental Gradle concepts, check out my free course Get Going with Gradle: the fastest way to a working knowledge of Gradle

Stop reading Gradle articles like these

This article helps you fix a specific problem, but it doesn't teach you the Gradle fundamentals you need to really help your team succeed.

Instead, follow a step-by-step process that makes getting started with Gradle easy.

Download this Free Quick-Start Guide to building simple Java projects with Gradle.

  • Learn to create and build Java projects in Gradle.
  • Understand the Gradle fundamentals.