Scroll to navigation

GRADLE(1) Gradle Command Line Manual GRADLE(1)

NAME

gradle - Adaptable, fast automation for all

SYNOPSIS

gradle [option...] [task...]

OPTIONS

A detailed guide of the command line interface is provided on Gradle's official website. The project itself does not provide a manpage, therefore maintaining it is error-prone and costly.

The summary of the options is provided below.

-?, -h, --help
Shows a help message with all available CLI options.
Prints Gradle, Groovy, Ant, JVM, and operating system version information.
Print out the full (very verbose) stacktrace for any exceptions. See also the documentation section COMMAND LINE LOGGING, LOGGING OPTIONS.
Print out the stacktrace also for user exceptions (e.g. compile error). See also the documentation section COMMAND LINE LOGGING, LOGGING OPTIONS.
Create a <https://gradle.com/build-scans> with fine-grained information about all aspects of your Gradle build.
Debug Gradle client (non-Daemon) process. Gradle will wait for you to attach a debugger at localhost:5005 by default.
Debug Gradle Daemon process.

PERFORMANCE OPTIONS

Try these options when optimizing build performance. Learn more about <https://guides.gradle.org/performance/>.

Many of these options can be specified in gradle.properties so command-line flags are not necessary. See the documentation section GRADLE CONFIGURATION PROPERTIES, CONFIGURING BUILD ENVIRONMENT GUIDE.

Toggles the Gradle build cache. Gradle will try to reuse outputs from previous builds. Default is off .
Toggles the documentation section CONFIGURATION ON DEMAND, CONFIGURE-ON-DEMAND. Only relevant projects are configured in this build run. Default is off .
Sets maximum number of workers that Gradle may use. _Default is number of processors_.
Build projects in parallel. For limitations of this option please see the documentation section PARALLEL EXECUTION. Default is off .
Generates a high-level performance report in the $buildDir/reports/profile directory. --scan is preferred.
Generate a build scan with detailed performance diagnostics.

image:img/gradle-core-test-build-scan-performance.png[Build Scan performance report]

==== Gradle daemon options You can manage the Gradle Daemon through the following command line options.

Use the Gradle Daemon to run the build. Starts the daemon if not running or existing daemon busy. Default is on .
Starts the Gradle Daemon in a foreground process.
Run gradle --status to list running and recently stopped Gradle daemons. Only displays daemons of the same Gradle version.
Run gradle --stop to stop all Gradle Daemons of the same version.
Gradle Daemon will stop itself after this number of milliseconds of idle time. _Default is 10800000_ (3 hours).

LOGGING OPTIONS

==== Setting log level You can customize the verbosity of Gradle logging with the following options, ordered from least verbose to most verbose. Learn more in the logging documentation.

Set logging level via Gradle properties.
Log errors only.
Set log level to warn.
Set log level to info.
Log in debug mode (includes normal stacktrace).

Lifecycle is the default log level.

==== Customizing log format You can control the use of rich output (colors and font variants) by specifying the "console" mode in the following ways:

Specify console mode via Gradle properties. Different modes described immediately below.
Specifies which type of console output to generate.

Set to plain to generate plain text only. This option disables all color and other rich output in the console output. This is the default when Gradle is _not_ attached to a terminal.

Set to auto (the default) to enable color and other rich output in the console output when the build process is attached to a console, or to generate plain text only when not attached to a console. _This is the default when Gradle is attached to a terminal._

Set to rich to enable color and other rich output in the console output, regardless of whether the build process is not attached to a console. When not attached to a console, the build output will use ANSI control characters to generate the rich output.

Set to verbose to enable color and other rich output like the rich, but output task names and outcomes at the lifecycle log level, as is done by default in Gradle 3.5 and earlier.

==== Showing or hiding warnings By default, Gradle won't display all warnings (e.g. deprecation warnings). Instead, Gradle will collect them and render a summary at the end of the build like:

---- Deprecated Gradle features were used in this build, making it incompatible with Gradle 5.0. ----

You can control the verbosity of warnings on the console with the following options:

Specify warning mode via the documentation section GRADLE PROPERTIES, GRADLE PROPERTIES. Different modes described immediately below.
Specifies how to log warnings. Default is summary.

Set to all to log all warnings.

Set to summary to suppress all warnings and log a summary at the end of the build.

Set to none to suppress all warnings, including the summary at the end of the build.

==== Rich Console Gradle's rich console displays extra information while builds are running.

image::img/rich-cli.png[alt="Gradle Rich Console"]

Features:

 * Logs above grouped by task that generated them
 * Progress bar and timer visually describe overall status
 * Parallel work-in-progress lines below describe what is happening now

EXECUTION OPTIONS

The following options affect how builds are executed, by changing what is built or how dependencies are resolved.

Run the build as a composite, including the specified build. See Composite Builds.
Specifies that the build should operate without accessing network resources. Learn more about the documentation section CONTROLLING DEPENDENCY CACHING COMMAND LINE,OPTIONS TO OVERRIDE DEPENDENCY CACHING.
Refresh the state of dependencies. Learn more about how to use this in the documentation section CONTROLLING DEPENDENCY CACHING COMMAND LINE,DEPENDENCY MANAGEMENT DOCS.
Run Gradle with all task actions disabled. Use this to show which task would have executed.

ENVIRONMENT OPTIONS

You can customize many aspects about where build scripts, settings, caches, and so on through the options below. Learn more about customizing your build environment.

Specifies the build file. For example: gradle --build-file=foo.gradle. The default is build.gradle, then build.gradle.kts, then myProjectName.gradle.
Specifies the settings file. For example: gradle --settings-file=somewhere/else/settings.gradle
Specifies the Gradle user home directory. The default is the .gradle directory in the user's home directory.
Specifies the start directory for Gradle. Defaults to current directory.
Specifies the project-specific cache directory. Default value is .gradle in the root project directory.
Don't search in parent directories for a settings.gradle file.
Sets a system property of the JVM, for example -Dmyprop=myvalue. See the documentation section GRADLE SYSTEM PROPERTIES.
Specifies an initialization script. See the documentation section INIT SCRIPTS.
Sets a project property of the root project, for example -Pmyprop=myvalue. See the documentation section PROJECT PROPERTIES.
Set JVM arguments.
Set JDK home dir.

BOOTSTRAPPING NEW PROJECTS

==== Creating new Gradle builds Use the built-in gradle init task to create a new Gradle builds, with new or existing projects.

---- ❯ gradle init ----

Most of the time you'll want to specify a project type. Available types include basic (default), java-library, java-application, and more. See init plugin documentation for details.

---- ❯ gradle init --type java-library ----

==== Standardize and provision Gradle The built-in gradle wrapper task generates a script, gradlew, that invokes a declared version of Gradle, downloading it beforehand if necessary.

---- ❯ gradle wrapper --gradle-version=4.4 ----

You can also specify --distribution-type=(bin|all), --gradle-distribution-url, --gradle-distribution-sha256-sum in addition to --gradle-version. Full details on how to use these options are documented in the Gradle wrapper section.

CONTINUOUS BUILD

Continuous Build allows you to automatically re-execute the requested tasks when task inputs change.

For example, you can continuously run the test task and all dependent tasks by running:

---- ❯ gradle test --continuous ----

Gradle will behave as if you ran gradle test after a change to sources or tests that contribute to the requested tasks. This means that unrelated changes (such as changes to build scripts) will not trigger a rebuild. In order to incorporate build logic changes, the continuous build must be restarted manually.

==== Terminating Continuous Build

If Gradle is attached to an interactive input source, such as a terminal, the continuous build can be exited by pressing CTRL-D (On Microsoft Windows, it is required to also press ENTER or RETURN after CTRL-D). If Gradle is not attached to an interactive input source (e.g. is running as part of a script), the build process must be terminated (e.g. using the kill command or similar). If the build is being executed via the Tooling API, the build can be cancelled using the Tooling API's cancellation mechanism.

==== Limitations and quirks

[NOTE] ==== Continuous build is an incubating feature. ====

There are several issues to be aware with the current implementation of continuous build. These are likely to be addressed in future Gradle releases.

===== Build cycles

Gradle starts watching for changes just before a task executes. If a task modifies its own inputs while executing, Gradle will detect the change and trigger a new build. If every time the task executes, the inputs are modified again, the build will be triggered again. This isn't unique to continuous build. A task that modifies its own inputs will never be considered up-to-date when run "normally" without continuous build.

If your build enters a build cycle like this, you can track down the task by looking at the list of files reported changed by Gradle. After identifying the file(s) that are changed during each build, you should look for a task that has that file as an input. In some cases, it may be obvious (e.g., a Java file is compiled with compileJava). In other cases, you can use --info logging to find the task that is out-of-date due to the identified files.

===== Restrictions with Java 9

Due to class access restrictions related to Java 9, Gradle cannot set some operating system specific options, which means that:

* On macOS, Gradle will poll for file changes every 10 seconds instead of every 2 seconds. * On Windows, Gradle must use individual file watches (like on Linux/Mac OS), which may cause continuous build to no longer work on very large projects.

===== Performance and stability

The JDK file watching facility relies on inefficient file system polling on macOS (see: <https://bugs.openjdk.java.net/browse/JDK-7133447>). This can significantly delay notification of changes on large projects with many source files.

Additionally, the watching mechanism may deadlock under _heavy_ load on macOS (see: <https://bugs.openjdk.java.net/browse/JDK-8079620>). This will manifest as Gradle appearing not to notice file changes. If you suspect this is occurring, exit continuous build and start again.

On Linux, OpenJDK's implementation of the file watch service can sometimes miss file system events (see: <https://bugs.openjdk.java.net/browse/JDK-8145981>).

===== Changes to symbolic links

 * Creating or removing symbolic link to files will initiate a build.
 * Modifying the target of a symbolic link will not cause a rebuild.
 * Creating or removing symbolic links to directories will not cause rebuilds.
 * Creating new files in the target directory of a symbolic link will not cause a rebuild.
 * Deleting the target directory will not cause a rebuild.

===== Changes to build logic are not considered

The current implementation does not recalculate the build model on subsequent builds. This means that changes to task configuration, or any other change to the build model, are effectively ignored.

SEE ALSO

<https://docs.gradle.org/current/userguide/command_line_interface.html>

AUTHORS

Gradle developers

2026-09-24 Gradle 4.6