Configuring the build environment is a powerful way to customize the build process. There are many mechanisms available. By leveraging these mechanisms, you can make your Gradle builds more flexible and adaptable to different environments and requirements.

Available mechanisms

Gradle provides multiple mechanisms for configuring the behavior of Gradle itself and specific projects:

Mechanism Information Example

Command line interface

Flags that configure build behavior and Gradle features

--rerun

Project properties

Properties specific to your Gradle project

TestFilter::isFailOnNoMatchingTests=false

System properties

Properties that are passed to the Gradle runtime (JVM)

http.proxyHost=somehost.org

Gradle properties

Properties that configure Gradle settings and the Java process that executes your build

org.gradle.logging.level=quiet

Environment variables

Properties that configure build behavior based on the environment

JAVA_HOME

Priority for configurations

When configuring Gradle behavior, you can use these methods, but you must consider their priority.

The following table lists these methods in order of highest to lowest precedence (the first one wins):

Priority Method Location Notes

1

Command-line

> Command line

Flags have precedence over properties and environment variables

2

System properties

> Project Root Dir

Stored in a gradle.properties file

3

Gradle properties

> GRADLE_USER_HOME
> Project Root Dir
> GRADLE_HOME

Stored in a gradle.properties file

4

Environment variables

> Environment

Sourced by the environment that executes Gradle

Here are all possible configurations of specifying the JDK installation directory in order of priority:

  1. Command Line

    $ ./gradlew exampleTask -Dorg.gradle.java.home=/path/to/your/java/home --scan

  2. Gradle Properties File

    gradle.properties
    org.gradle.java.home=/path/to/your/java/home

  3. Environment Variable

    $ export JAVA_HOME=/path/to/your/java/home

The gradle.properties file

Gradle properties, system properties, and project properties can be found in the gradle.properties file:

gradle.properties
# Gradle properties
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.jvmargs=-Duser.language=en -Duser.country=US -Dfile.encoding=UTF-8

# System properties
systemProp.pts.enabled=true
systemProp.log4j2.disableJmx=true
systemProp.file.encoding = UTF-8

# Project properties
kotlin.code.style=official
android.nonTransitiveRClass=false
spring-boot.version = 2.2.1.RELEASE

You can place the gradle.properties file in the root directory of your project, the Gradle user home directory (GRADLE_USER_HOME), or the directory where Gradle is optionally installed (GRADLE_HOME).

When resolving properties, Gradle first looks in the project-level gradle.properties file, then in the user-level gradle.properties file located in GRADLE_USER_HOME, and finally in the gradle.properties file located in GRADLE_HOME, with project-level properties taking precedence over user-level and installation-level properties.

Project properties

Project properties are specific to your Gradle project, they can be used to customize your build. Project properties can be accessed in your build files and get passed in from an external source when your build is executed. Project properties can be retrieved lazily using providers.gradleProperty().

Setting a project property

You have four options to add project properties, listed in order of priority:

  1. Command Line: You can add project properties directly to your Project object via the -P command line option.

    $ ./gradlew build -PmyProperty='Hi, world'

  2. System Property: Gradle creates specially-named system properties for project properties which you can set using the -D command line flag or gradle.properties file. For the project property myProperty, the system property created is called org.gradle.project.myProperty.

    $ ./gradlew build -Dorg.gradle.project.myProperty='Hi, world'
    gradle.properties
    org.gradle.project.myProperty='Hi, world'

  3. Gradle Properties File: You can also set project properties in gradle.properties files.

    gradle.properties
    myProperty='Hi, world'

  4. Environment Variables: You can set project properties with environment variables. If the environment variable name looks like ORG_GRADLE_PROJECT_myProperty='Hi, world', then Gradle will set a myProperty property on your project object, with the value of Hi, world.

    $ export ORG_GRADLE_PROJECT_myProperty='Hi, world'

    This is typically the preferred method for supplying project properties, especially secrets, to unattended builds like those running on CI servers.

It is possible to change the behavior of a task based on project properties specified at invocation time. Suppose you’d like to ensure release builds are only triggered by CI. A simple way to handle this is through an isCI project property:

build.gradle.kts
tasks.register("performRelease") {
    val isCI = providers.gradleProperty("isCI")
    doLast {
        if (isCI.isPresent) {
            println("Performing release actions")
        } else {
            throw InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}
build.gradle
tasks.register('performRelease') {
    def isCI = providers.gradleProperty("isCI")
    doLast {
        if (isCI.present) {
            println("Performing release actions")
        } else {
            throw new InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}
$ ./gradlew performRelease -PisCI=true --quiet
Performing release actions

Note that running ./gradlew performRelease yields the same results as long as your gradle.properties file includes isCI=true:

gradle.properties
isCI=true
$ ./gradlew performRelease --quiet
Performing release actions

Command-line flags

The command line interface and the available flags are described in its own section.

System properties

System properties are variables set at the JVM level and accessible to the Gradle build process. System properties can be retrieved lazily using providers.systemProperty().

Setting a system property

You have two options to add system properties listed in order of priority:

  1. Command Line: Using the -D command-line option, you can pass a system property to the JVM, which runs Gradle. The -D option of the gradle command has the same effect as the -D option of the java command.

    $ ./gradlew build -Dgradle.wrapperUser=myuser

  2. Gradle Properties File: You can also set system properties in gradle.properties files with the prefix systemProp.

    gradle.properties
    systemProp.gradle.wrapperUser=myuser

System properties reference

For a quick reference, the following are common system properties:

gradle.wrapperUser=(myuser)

Specify username to download Gradle distributions from servers using HTTP Basic Authentication.

gradle.wrapperPassword=(mypassword)

Specify password for downloading a Gradle distribution using the Gradle wrapper.

gradle.user.home=(path to directory)

Specify the GRADLE_USER_HOME directory.

https.protocols

Specify the supported TLS versions in a comma-separated format. e.g., TLSv1.2,TLSv1.3.

Additional Java system properties are listed here.

In a multi-project build, systemProp properties set in any project except the root will be ignored. Only the root project’s gradle.properties file will be checked for properties that begin with systemProp.

Gradle properties

Gradle properties configure Gradle itself and usually have the name org.gradle.\*. Gradle properties should not be used in build logic, their values should not be read/retrieved.

Setting a Gradle property

You have two options to add Gradle properties listed in order of priority:

  1. Command Line: Using the -D command-line option, you can pass a Gradle property:

    $ ./gradlew build -Dorg.gradle.caching.debug=false

  2. Gradle Properties File: Place these settings into a gradle.properties file and commit it to your version control system.

    gradle.properties
    org.gradle.caching.debug=false

The final configuration considered by Gradle is a combination of all Gradle properties set on the command line and your gradle.properties files. If an option is configured in multiple locations, the first one found in any of these locations wins:

Priority Method Location Details

1

Command line interface

.

In the command line using -D.

2

gradle.properties file

GRADLE_USER_HOME

Stored in a gradle.properties file in the GRADLE_USER_HOME.

3

gradle.properties file

Project Root Dir

Stored in a gradle.properties file in a project directory, then its parent project’s directory up to the project’s root directory.

4

gradle.properties file

GRADLE_HOME

Stored in a gradle.properties file in the GRADLE_HOME, the optional Gradle installation directory.
The location of the GRADLE_USER_HOME may have been changed beforehand via the -Dgradle.user.home system property passed on the command line.

Gradle properties reference

For reference, the following properties are common Gradle properties:

org.gradle.caching=(true,false)

When set to true, Gradle will reuse task outputs from any previous build when possible, resulting in much faster builds.

Default is false; the build cache is not enabled.

org.gradle.caching.debug=(true,false)

When set to true, individual input property hashes and the build cache key for each task are logged on the console.

Default is false.

org.gradle.configuration-cache=(true,false)

Enables configuration caching. Gradle will try to reuse the build configuration from previous builds.

Default is false.

org.gradle.configureondemand=(true,false)

Enables incubating configuration-on-demand, where Gradle will attempt to configure only necessary projects.

Default is false.

org.gradle.console=(auto,plain,rich,verbose)

Customize console output coloring or verbosity.

Default depends on how Gradle is invoked.

org.gradle.continue=(true,false)

If enabled, continue task execution after a task failure, else stop task execution after a task failure.

Default is false.

org.gradle.daemon=(true,false)

When set to true the Gradle Daemon is used to run the build.

Default is true.

org.gradle.daemon.idletimeout=(# of idle millis)

Gradle Daemon will terminate itself after a specified number of idle milliseconds.

Default is 10800000 (3 hours).

org.gradle.debug=(true,false)

When set to true, Gradle will run the build with remote debugging enabled, listening on port 5005. Note that this is equivalent to adding -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 to the JVM command line and will suspend the virtual machine until a debugger is attached.

Default is false.

org.gradle.java.home=(path to JDK home)

Specifies the Java home for the Gradle build process. The value can be set to either a jdk or jre location; however, using a JDK is safer depending on what your build does. This does not affect the version of Java used to launch the Gradle client VM.

You can also control the JVM used to run Gradle itself using the Daemon JVM criteria.

Default is derived from your environment (JAVA_HOME or the path to java) if the setting is unspecified.

org.gradle.jvmargs=(JVM arguments)

Specifies the JVM arguments used for the Gradle Daemon. The setting is particularly useful for configuring JVM memory settings for build performance. This does not affect the JVM settings for the Gradle client VM.

Default is -Xmx512m "-XX:MaxMetaspaceSize=384m".

org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)

When set to quiet, warn, info, or debug, Gradle will use this log level. The values are not case-sensitive.

Default is lifecycle level.

org.gradle.parallel=(true,false)

When configured, Gradle will fork up to org.gradle.workers.max JVMs to execute projects in parallel.

Default is false.

org.gradle.priority=(low,normal)

Specifies the scheduling priority for the Gradle daemon and all processes launched by it.

Default is normal.

org.gradle.projectcachedir=(directory)

Specify the project-specific cache directory. Defaults to .gradle in the root project directory."

Default is .gradle.

org.gradle.unsafe.isolated-projects=(true,false)

Enables project isolation, which enables configuration caching.

Default is false.

org.gradle.vfs.verbose=(true,false)

Configures verbose logging when watching the file system.

Default is false.

org.gradle.vfs.watch=(true,false)

Toggles watching the file system. When enabled, Gradle reuses information it collects about the file system between builds.

Default is true on operating systems where Gradle supports this feature.

org.gradle.warning.mode=(all,fail,summary,none)

When set to all, summary, or none, Gradle will use different warning type display.

Default is summary.

org.gradle.workers.max=(max # of worker processes)

When configured, Gradle will use a maximum of the given number of workers.

Default is the number of CPU processors.

Environment variables

Gradle provides a number of environment variables, which are listed below. Environment variables can be retrieved lazily using providers.environmentVariable().

Setting environment variables

Let’s take an example that sets the $JAVA_HOME environment variable:

$ set JAVA_HOME=C:\Path\To\Your\Java\Home   // Windows
$ export JAVA_HOME=/path/to/your/java/home  // Mac/Linux

You can access environment variables as properties in the build script using the System.getenv() method:

task printEnvVariables {
    doLast {
        println "JAVA_HOME: ${System.getenv('JAVA_HOME')}"
    }
}

Environment variables reference

The following environment variables are available for the gradle command:

GRADLE_HOME

Installation directory for Gradle.

Can be used to specify a local Gradle version instead of using the wrapper.

You can add GRADLE_HOME/bin to your PATH for specific applications and use cases (such as testing an early release for Gradle).

JAVA_OPTS

Used to pass JVM options and custom settings to the JVM.

export JAVA_OPTS="-Xmx18928m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dkotlin.daemon.jvm.options=-Xmx6309m"

GRADLE_OPTS

Specifies JVM arguments to use when starting the Gradle client VM.

The client VM only handles command line input/output, so one would rarely need to change its VM options.

The actual build is run by the Gradle daemon, which is not affected by this environment variable.

GRADLE_USER_HOME

Specifies the GRADLE_USER_HOME directory for Gradle to store its global configuration properties, initialization scripts, caches, log files and more.

Defaults to USER_HOME/.gradle if not set.

JAVA_HOME

Specifies the JDK installation directory to use for the client VM.

This VM is also used for the daemon unless a different one is specified in a Gradle properties file with org.gradle.java.home or using the Daemon JVM criteria.

GRADLE_LIBS_REPO_OVERRIDE

Overrides for the default Gradle library repository.

Can be used to specify a default Gradle repository URL in org.gradle.plugins.ide.internal.resolver.

Useful override to specify an internally hosted repository if your company uses a firewall/proxy.