The command-line interface is one of the primary methods of interacting with Gradle. The following serves as a reference of executing and customizing Gradle use of a command-line or when writing scripts or configuring continuous integration.
Use of the Gradle Wrapper is highly encouraged. You should substitute
gradle in all following examples when using the Wrapper.
Executing Gradle on the command-line conforms to the following structure. Options are allowed before and after task names.
gradle [taskName...] [--option-name...]
If multiple tasks are specified, they should be separated with a space.
Options that accept values can be specified with or without
= between the option and argument; however, use of
= is recommended.
Options that enable behavior have long-form options with inverses specified with
--no-. The following are opposites.
Many long-form options, have short option equivalents. The following are equivalent:
Many command-line flags can be specified in
The following sections describe use of the Gradle command-line interface, grouped roughly by user goal. Some plugins also add their own command line options, for example
--tests for Java test filtering. For more information on exposing command line options for your own tasks, see Declaring and using command-line options.
You can learn about what projects and tasks are available in the project reporting section.
Most builds support a common set of tasks known as lifecycle tasks. These include the
In order to execute a task called "myTask" on the root project, type:
$ gradle :myTask
This will run the single "myTask" and also all of its task dependencies.
Specify options for a task
To pass an option to a task, prefix the option name with
-- after the task name:
$ gradle exampleTask --exampleOption=exampleValue
Disambiguate task options from built-in options
Gradle does not prevent tasks from registering options that conflict with Gradle’s built-in options, like
You can disambiguate conflicting task options from Gradle’s built-in options with a
-- delimiter before the task name in your command:
$ gradle [--built-in-option-name...] -- [taskName...] [--task-option-name...]
Consider a task named "mytask" that accepts an option named "profile":
If you run
gradle mytask --profile, Gradle accepts
--profileas the built-in Gradle option.
If you run
gradle — mytask --profile=exampleValue, Gradle passes
--profileas a task option.
Executing tasks in multi-project builds
In a multi-project build, subproject tasks can be executed with ":" separating subproject name and task name. The following are equivalent when run from the root project:
$ gradle :my-subproject:taskName $ gradle my-subproject:taskName
You can also run a task for all subprojects by using a task selector that consists of the task name only. For example, this will run the "test" task for all subprojects when invoked from the root project directory:
$ gradle test
Some tasks selectors, like
When invoking Gradle from within a subproject, the project name should be omitted:
$ cd my-subproject $ gradle taskName
When executing the Gradle Wrapper from subprojects, one must reference
Executing multiple tasks
You can also specify multiple tasks. The tasks will be executed as quickly as possible while still honoring task dependencies. Precise order of execution is determined by the tasks' dependencies, and a task having no dependencies may execute earlier than it is listed on the command-line. For example, the following will execute the
deploy tasks in the order that they are listed on the command-line and will also execute the dependencies for each task.
$ gradle test deploy
Command line order safety
Although Gradle will always attempt to execute the build as quickly as possible, command line ordering safety will also be honored. For example, the following will execute
build along with their dependencies.
$ gradle clean build
However, the intention implied in the command line order is that
clean should run first, and then
build. It would be incorrect to execute
build, even if doing so would cause the build to execute faster, since
clean would remove what
build created. Conversely, if the command line order was
build followed by
clean, it would not be correct to execute
build. Although Gradle will execute the build as quickly as possible, it will also respect the safety of the order of tasks specified on the command line and ensure that
clean runs before
build when specified in that order.
Note that command line order safety relies on tasks properly declaring what they create, consume or remove. See up-to-date checks for further information.
Excluding tasks from execution
You can exclude a task from being executed using the
--exclude-task command-line option and providing the name of the task to exclude.
$ gradle dist --exclude-task test > Task :compile compiling source > Task :dist building the distribution BUILD SUCCESSFUL in 0s 2 actionable tasks: 2 executed
You can see that the
test task is not executed, even though it is a dependency of the
dist task. The
test task’s dependencies such as
compileTest are not executed either. Those dependencies of
test that are required by another task, such as
compile, are still executed.
Forcing tasks to execute
You can force Gradle to execute all tasks ignoring up-to-date checks using the
$ gradle test --rerun-tasks
This will force
test and all task dependencies of
test to execute. It’s a little like running
gradle clean test, but without the build’s generated output being deleted.
Alternatively, you can tell Gradle to rerun a specific task using the
--rerun built-in task option.
Continue the build after a task failure
By default, Gradle aborts execution and fails the build when any task fails.
This allows the build to complete sooner and prevents cascading failures from obfuscating the root cause of an error.
You can use the
--continue option to force Gradle to execute every task when a failure occurs:
$ gradle test --continue
When executed with
--continue, Gradle executes every task in the build if all of the dependencies for that task completed without failure.
For example, tests do not run if there is a compilation error in the code under test because the test task depends on the compilation task.
Gradle outputs each of the encountered failures at the end of the build.
Many test suites fail the entire "test" task if any tests fail. Code coverage and reporting tools frequently run after the test task, so this "fail fast" behavior may halt execution before those tools run.
When you specify tasks on the command-line, you don’t have to provide the full name of the task. You only need to provide enough of the task name to uniquely identify the task. For example, it’s likely
gradle che is enough for Gradle to identify the
The same applies for project names. You can execute the
check task in the
library subproject with the
gradle lib:che command.
You can use camel case patterns for more complex abbreviations. These patterns are expanded to match camel case and kebab case names. For example the pattern
foBa (or even
More concretely, you can run the
compileTest task in the
my-awesome-library subproject with the
gradle mAL:cT command.
$ gradle mAL:cT > Task :my-awesome-library:compileTest compiling unit tests BUILD SUCCESSFUL in 0s 1 actionable task: 1 executed
You can also use these abbreviations with the
-x command-line option.
Tracing name expansion
For complex projects, it might not be obvious if the intended tasks were executed. When using abbreviated names, a single typo can lead to the execution of unexpected tasks.
When INFO, or more verbose logging is enabled, the output will contain extra information about the project and task name expansion. For example, when executing the
mAL:cT command on the previous example, the following log messages will be visible:
No exact project with name ‘:mAL’ has been found. Checking for abbreviated names. Found exactly one project that matches the abbreviated name ‘:mAL’: ':my-awesome-library'. No exact task with name ‘:cT’ has been found. Checking for abbreviated names. Found exactly one task name, that matches the abbreviated name ‘:cT’: ':compileTest'.
The following are task conventions applied by built-in and most major Gradle plugins.
Computing all outputs
It is common in Gradle builds for the
build task to designate assembling all outputs and running all checks.
$ gradle build
It is common for applications to be run with the
run task, which assembles the application and executes some script or binary.
$ gradle run
Running all checks
It is common for all verification tasks, including tests and linting, to be executed using the
$ gradle check
You can delete the contents of the build directory using the
clean task, though doing so will cause pre-computed outputs to be lost, causing significant additional build time for the subsequent task execution.
$ gradle clean
Gradle provides several built-in tasks which show particular details of your build. This can be useful for understanding the structure and dependencies of your build, and for debugging problems.
You can get basic help about available reporting options using
gradle projects gives you a list of the sub-projects of the selected project, displayed in a hierarchy.
$ gradle projects
You also get a project report within build scans. Learn more about creating build scans.
gradle tasks gives you a list of the main tasks of the selected project. This report shows the default tasks for the project, if any, and a description for each task.
$ gradle tasks
By default, this report shows only those tasks which have been assigned to a task group. You can obtain more information in the task listing using the
$ gradle tasks --all
If you need to be more precise, you can display only the tasks from a specific group using the
$ gradle tasks --group="build setup"
Show task usage details
gradle help --task someTask gives you detailed information about a specific task.
$ gradle -q help --task libs Detailed task information for libs Paths :api:libs :webapp:libs Type Task (org.gradle.api.Task) Options --rerun Causes the task to be re-run even if up-to-date. Description Builds the JAR Group build
This information includes the full task path, the task type, possible task-specific command line options and the description of the given task.
Build scans give a full, visual report of what dependencies exist on which configurations, transitive dependencies, and dependency version selection.
$ gradle myTask --scan
This will give you a link to a web-based report, where you can find dependency information like this.
Learn more in Viewing and debugging dependencies.
Listing project dependencies
gradle dependencies gives you a list of the dependencies of the selected project, broken down by configuration. For each configuration, the direct and transitive dependencies of that configuration are shown in a tree. Below is an example of this report:
$ gradle dependencies
Concrete examples of build scripts and output available in the Viewing and debugging dependencies.
gradle buildEnvironment visualises the buildscript dependencies of the selected project, similarly to how
gradle dependencies visualizes the dependencies of the software being built.
$ gradle buildEnvironment
gradle dependencyInsight gives you an insight into a particular dependency (or dependencies) that match specified input.
$ gradle dependencyInsight
Since a dependency report can get large, it can be useful to restrict the report to a particular configuration. This is achieved with the optional
Listing project properties
gradle properties gives you a list of the properties of the selected project.
$ gradle -q api:properties ------------------------------------------------------------ Project ':api' - The shared API for the application ------------------------------------------------------------ allprojects: [project ':api'] ant: org.gradle.api.internal.project.DefaultAntBuilder@12345 antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@12345 artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler_Decorated@12345 asDynamicObject: DynamicObject for project ':api' baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope@12345
You can also query a single property with the optional
$ gradle -q api:properties --property allprojects ------------------------------------------------------------ Project ':api' - The shared API for the application ------------------------------------------------------------ allprojects: [project ':api']
Gradle provides bash and zsh tab completion support for tasks, options, and Gradle properties through gradle-completion, installed separately.
Shows a help message with the built-in CLI options. To show project-contextual options, including help on a specific task, see the
Prints Gradle, Groovy, Ant, JVM, and operating system version information and exit without executing any tasks.
Prints Gradle, Groovy, Ant, JVM, and operating system version information and continue execution of specified tasks.
Print out the full (very verbose) stacktrace for any exceptions. See also logging options.
Print out the stacktrace also for user exceptions (e.g. compile error). See also logging options.
Create a build scan 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
Specifies the host address to listen on or connect to when debug is enabled. In the server mode on Java 9 and above, passing
*for the host will make the server listen on all network interfaces. By default, no host address is passed to JDWP, so on Java 9 and above, the loopback address is used, while earlier versions listen on all interfaces.
Specifies the port number to listen on when debug is enabled. Default is
If set to
trueand debugging is enabled, Gradle will run the build with the socket-attach mode of the debugger. Otherwise, the socket-listen mode is used. Default is
When set to
trueand debugging is enabled, the JVM running Gradle will suspend until a debugger is attached. Default is
Debug Gradle Daemon process.
Try these options when optimizing build performance. Learn more about improving performance of Gradle builds here.
Many of these options can be specified in
gradle.properties so command-line flags are not necessary. See the configuring build environment guide.
Toggles the Gradle build cache. Gradle will try to reuse outputs from previous builds. Default is off.
Toggles the Configuration Cache. Gradle will try to reuse the build configuration from previous builds. Default is off.
Configures how the configuration cache handles problems. Default is
warnto report problems without failing the build.
failto report problems and fail the build if there are any problems.
Toggles 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, see Parallel Project Execution. Default is off.
Specifies the scheduling priority for the Gradle daemon and all processes launched by it. Values are
low. Default is normal.
Generates a high-level performance report in the
Generate a build scan with detailed performance diagnostics.
Toggles watching the file system. When enabled Gradle re-uses information it collects about the file system between builds. Enabled by default on operating systems where Gradle supports this feature.
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.
gradle --statusto list running and recently stopped Gradle daemons. Only displays daemons of the same Gradle version.
gradle --stopto stop all Gradle Daemons of the same version.
-Dorg.gradle.daemon.idletimeout=(number of milliseconds)
Gradle Daemon will stop itself after this number of milliseconds of idle time. Default is 10800000 (3 hours).
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.
plainto 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.
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.
richto 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.
verboseto 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 Gradle properties. Different modes described immediately below.
Specifies how to log warnings. Default is
allto log all warnings.
failto log all warnings and fail the build if there are any warnings.
summaryto suppress all warnings and log a summary at the end of the build.
noneto suppress all warnings, including the summary at the end of the build.
Gradle’s rich console displays extra information while builds are running.
Progress bar and timer visually describe overall status
Parallel work-in-progress lines below describe what is happening now
Colors and fonts are used to highlight important output and errors
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 options to override dependency caching.
Refresh the state of dependencies. Learn more about how to use this in the dependency management docs.
Continue task execution after a task failure. See Continuing the build when a failure occurs.
Run Gradle with all task actions disabled. Use this to show which task would have executed.
Enables continuous build. Gradle does not exit and will re-execute tasks when task file inputs change. See Continuous Build for more details.
Indicates that all resolved configurations that are lockable should have their lock state persisted. Learn more about this in dependency locking.
Indicates that versions for the specified modules have to be updated in the lock file. This flag also implies
--write-locks. Learn more about this in dependency locking.
Do not rebuild project dependencies. Useful for debugging and fine-tuning
buildSrc, but can lead to wrong results. Use with caution!
Dependency verification options
Learn more about this in dependency verification.
Configures the dependency verification mode, see what the options mean here. The default mode is
Generates checksums for dependencies used in the project (comma-separated list) for dependency verification. See how to bootstrap dependency verification.
Refresh the public keys used for dependency verification.
Exports the public keys used for dependency verification.
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
Specifies the settings file. For example:
Specifies the Gradle user home directory. The default is the
.gradledirectory 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
.gradlein the root project directory.
Sets a system property of the JVM, for example
-Dmyprop=myvalue. See System Properties.
Specifies an initialization script. See Init Scripts.
Sets a project property of the root project, for example
-Pmyprop=myvalue. See Project Properties.
Set JVM arguments.
Set JDK home dir.
Tasks may define task-specific options. Differently than most of the global options described in the sections above (which are interpreted by Gradle itself, can appear anywhere in the command line, and can be listed using the
are consumed and interpreted by the tasks themselves;
must be specified immediately after the task in the command-line;
may be listed using
gradle help --task someTask(see Show task usage details).
To learn how to declare command-line options for your own tasks, see Declaring and Using Command Line Options.
Built-in task options
Built-in task options are options available as task options for all tasks. At this time, the following built-in task options exist:
Causes the task to be re-run even if up-to-date. Similar to
--rerun-tasks, but for a specific task.
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
java-application, and more. See init plugin documentation for details.
$ gradle init --type java-library
Standardize and provision Gradle
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
--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 allows you to automatically re-execute the requested tasks when task inputs change.
You can execute the build in this mode using the
--continuous command-line option.
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.
Continuous build uses file system watching to detect changes to the inputs.
If file system watching does not work on your system, then continuous build won’t work either.
In particular, continuous build does not work when using
See Watching the file system for more information.
When Gradle detects a change to the inputs, it will not trigger the build immediately.
Instead, it will wait until no additional changes are detected for a certain period of time - the quiet period.
You can configure the quiet period in milliseconds by the Gradle property
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
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.
Under some circumstances continuous build may not detect changes to inputs.
Creating input directories
Sometimes, creating an input directory that was previously missing does not trigger a build, due to the way file system watching works.
For example, creating the
src/main/java directory may not trigger a build.
Similarly, if the input is a filtered file tree and no files are matching the filter, the creation of matching files may not trigger a build.
Inputs of untracked tasks
Changes to the inputs of untracked tasks or tasks that have no outputs may not trigger a build.
Changes to files outside of project directories
Gradle only watches for changes to files inside the project directory. Changes to files outside of the project directory will go undetected and not trigger a build.
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
In other cases, you can use
--info logging to find the task that is out-of-date due to the identified files.
Changes to symbolic links
In general, Gradle will not detect changes to symbolic links or to files referenced via symbolic links.
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.