Gradle Properties: Build and Configuration Example

In this detailed Gradle Properties tutorial, we shall see how to access several default properties in Gradle, and how to set our custom properties. Also, what methods are to set these properties and how Gradle processes them.

1. Why should we use Gradle Properties?

As developers, we provide high-quality code that is scalable and easy to read; Gradle’s properties allow us to perform these tasks, in addition to some cases optimize the compilation and execution of them.

2. What do we need?

As described in the previous example (Gradle Hello World Tutorial), we need Gradle fully functional. Please review the part of the installation and then continue with this example.

3. Types of Gradle’s Properties

In Gradle there are two types of properties, System properties and Project properties. The first of them, are properties used to configure the JVM that supports the execution of the builds, and the second type are for parameterizing variables in our projects, like names, paths, and other useful approaches.

3.1 System Properties

We can set these properties via environment variables, setting the GRADLE_OPTS or JAVA_OPTS values to manage, for example the Java home, Heap and PermGem Spaces, or Gradle daemon activation.

Then, go to the environment variables in windows users, and set the GRADLE_OPTS variable with the value -Dorg.gradle.daemon=true.

Gradle System Properties Configuration
Gradle System Properties Configuration

With this property, we active a Gradle daemon that loads all the libraries and essential classes for the build, and when we run Gralde, only the build is executed, because the JVM and all other required libraries are already running, establishing a powerful improvement.

See how this affects the build’s time.

Without daemon.

Gradle Build no Daemon
Gradle Build no Daemon

Daemon activated.

Gradle Build Daemon ON
Gradle Build Daemon ON

Setting system properties, we can manage common properties to all projects, and how to improve the performance with JVM memory management and gradle’s daemon.

In addition, we can set these properties in console with the -D Java command option. See how to do that.

E:\JavaCodeGeeks JCG\Gradle Properties Tutorial>gradle helloWorld -Dorg.gradle.daemon=false
Welcome to JCG Gradle Tutorial


Total time: 1.873 secs

There are some other System Properties:

  •, Specifies the Java Home for the Gradle build process.
  • org.gradle.jvmargs, Manage the memory settings for the JVM
  • org.gradle.configureondemand, Enables a new incubating and building mode, that’s an advanced feature when we work with multi-projects, which results in a faster builds.
  • org.gradle.parallel, Enables the parallel mode for incubating mode.

3.2 Project Properties

3.2.1 Gradle’s Properties, hello!

Gradle offers a wide list of default properties for the current build, we can print all running this simple command in the console: gradle properties. This is equivalent to the Properties in the Gradle “Hello World” Example.

E:\JavaCodeGeeks JCG\Gradle Properties Tutorial>gradle properties

Root project

allprojects: [root project 'Gradle Properties Tutorial']
ant: org.gradle.api.internal.project.DefaultAntBuilder@33666fbb
antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@7e10
artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler_Decorate
asDynamicObject: org.gradle.api.internal.ExtensibleDynamicObject@7ff37476
baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderS
beforHelloWorld: task ':beforHelloWorld'
buildDir: E:\JavaCodeGeeks JCG\Gradle Properties Tutorial\build
buildFile: E:\JavaCodeGeeks JCG\Gradle Properties Tutorial\build.gradle
buildScriptSource: org.gradle.groovy.scripts.UriScriptSource@608a1b4e
buildscript: org.gradle.api.internal.initialization.DefaultScriptHandler@65037d6
childProjects: {}
class: class org.gradle.api.internal.project.DefaultProject_Decorated
classLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope
components: []
configurationActions: org.gradle.configuration.project.DefaultProjectConfigurati
configurations: []
convention: org.gradle.api.internal.plugins.DefaultConvention@18740ad1
defaultTasks: [beforHelloWorld]
dependencies: org.gradle.api.internal.artifacts.dsl.dependencies.DefaultDependen
depth: 0
description: null
ext: org.gradle.api.internal.plugins.DefaultExtraPropertiesExtension@2b90cc9
extensions: org.gradle.api.internal.plugins.DefaultConvention@18740ad1
fileOperations: org.gradle.api.internal.file.DefaultFileOperations@5a6bc081
fileResolver: org.gradle.api.internal.file.BaseDirFileResolver@3e3155a8
gradle: build 'Gradle Properties Tutorial'
helloWorld: task ':helloWorld'
inheritedScope: org.gradle.api.internal.ExtensibleDynamicObject$InheritedDynamic
logger: org.gradle.api.logging.Logging$LoggerImpl@767c9c02
logging: org.gradle.logging.internal.DefaultLoggingManager@6aed5294
modelRegistry: org.gradle.model.internal.registry.DefaultModelRegistry@49d7572c
module: org.gradle.api.internal.artifacts.ProjectBackedModule@556edb6b
name: Gradle Properties Tutorial
parent: null
parentIdentifier: null
path: :
pluginManager: org.gradle.api.internal.plugins.DefaultPluginManager_Decorated@26
plugins: [org.gradle.api.plugins.HelpTasksPlugin@751f265a]
processOperations: org.gradle.api.internal.file.DefaultFileOperations@5a6bc081
project: root project 'Gradle Properties Tutorial'
projectDir: E:\JavaCodeGeeks JCG\Gradle Properties Tutorial
projectEvaluationBroadcaster: ProjectEvaluationListener broadcast
projectEvaluator: org.gradle.configuration.project.LifecycleProjectEvaluator@703
projectRegistry: org.gradle.api.internal.project.DefaultProjectRegistry@600e7a58

properties: {...}
repositories: []
resources: org.gradle.api.internal.resources.DefaultResourceHandler@3e4eede1
rootDir: E:\JavaCodeGeeks JCG\Gradle Properties Tutorial
rootProject: root project 'Gradle Properties Tutorial'
scriptHandlerFactory: org.gradle.api.internal.initialization.DefaultScriptHandle
scriptPluginFactory: org.gradle.configuration.DefaultScriptPluginFactory@579ab80
serviceRegistryFactory: org.gradle.internal.service.scopes.ProjectScopeServices$
services: ProjectScopeServices
standardOutputCapture: org.gradle.logging.internal.DefaultLoggingManager@6aed529
state: project state 'EXECUTED'
status: release
subprojects: []
tasks: [task ':beforHelloWorld', task ':helloWorld', task ':properties']
version: unspecified


Total time: 0.958 secs

These are a lot of properties, we only want to know how to read the default project properties.

3.2.2 Custom Project Properties in Script

If we want to add our custom properties, we have to define them in a build script with the ext{} block.

	myFirstProperty = 'myCustomPropertyValue'

task showPropertiesTask << {
	println myFirstProperty

After running the build file, we get this output:

E:\JavaCodeGeeks JCG\Gradle Properties Tutorial>gradle sPT


Total time: 1.344 secs

3.2.3 Setting Properties in Command Line

Instead of setting the properties in a build script (that’s not a good practice, the best approach is a properties file), we can use the -P command-line option to add any custom property.

Then, the build script has a task that prints the value of two properties.

task showPropertiesTask << {
	println "Version: $version"
	println "Custom property: $customProperty"

Running the script with this command gradle -Pversion=2.3.3 -PcustomProperty=myCustomValue showPropertiesTask, we get the following output.

E:\JavaCodeGeeks JCG\Gradle Properties Tutorial>gradle -Pversion=2.3.3 -PcustomProperty=myCustomValue showPropertiesTask
Version: 2.3.3
Custom property: myCustomValue


Total time: 2.67 secs

3.2.4 Setting Properties using an external file

So, we look at the optimal way to set our project properties, through an external file. The file needs to be named and it should be a plain text file with the name of the property and its value in the same line.

We now create a file in the same directory of our build.gradle file, with the following contents:

version = 3.0
customProperty = This value is obtained from

We use our previous build script to show the properties, after running the gradle script we get the following output:

E:\JavaCodeGeeks JCG\Gradle Properties Tutorial>gradle showPropertiesTask
Version: 3.0
Custom property: This value is obtained from


Total time: 0.943 secs

A useful concept, is the main Gradle directory. If we put the there, these properties take precedence over those that are in the project. In windows this directory is $USER_HOME/.gradle.

Gradle User Home Properties
Gradle User Home Properties

version = 4.0
customProperty = This value is obtained from in user home

Then, we add another file in this directory and run the gradle build, we get the following output.

E:\JavaCodeGeeks JCG\Gradle Properties Tutorial>gradle showPropertiesTask
Version: 4.0
Custom property: This value is obtained from in user home


Total time: 1.45 secs

4. Key Points

So, here are some tips to take note of:

  • We can set 2 types of properties, for tunning memory management and to customize our projects.
  • We can pass both properties in command-line with the -D and -P options.
  • A property defined in the properties file in the Gradle user home directory overrides the property values defined in a properties file in the project directory.
  • We can set our gradle properties in the Gradle home user directory or in a project directory.
  • The first directory where gradle lookup for properties is $USER_HOME/.gradle
  • Setting the Gradle daemon, we get a better performance in the build process.

5. Download the Gradle Scripts

You can download the full source code of this example here: Gradle Configuration Properties Tutorial

Andres Cespedes

Andres is a Java Software Craftsman from Medellin Colombia, who strongly develops on DevOps practices, RESTful Web Services, Continuous integration and delivery. Andres is working to improve software process and modernizing software culture on Colombia.
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button