Gradle Build Tool is a fast, dependable, and adaptable open-source build automation tool with an elegant and extensible declarative build language.

In this User Manual, Gradle Build Tool is abbreviated Gradle.

Gradle is a widely used and mature tool with an active community and a strong developer ecosystem.

Gradle, Inc. provides a free service called Build Scan® that provides extensive information and insights about your builds. You can view scans to identify problems or share them for debugging help.

The Gradle User Manual is the official documentation for the Gradle Build Tool.

Information on Gradle releases and how to install Gradle is found on the Installation page.

The Gradle User Manual is broken down into the following sections:

If all you want to do is run an existing Gradle project, then you don’t need to install Gradle if the build uses the Gradle Wrapper. This is identifiable by the presence of the gradlew or gradlew.bat files in the root of the project:

If the gradlew or gradlew.bat files are already present in your project, you do not need to install Gradle. But you need to make sure your system satisfies Gradle’s prerequisites.

You can follow the steps in the Upgrading Gradle section if you want to update the Gradle version for your project. Please use the Gradle Wrapper to upgrade Gradle.

Android Studio comes with a working installation of Gradle, so you don’t need to install Gradle separately when only working within that IDE.

If you do not meet the criteria above and decide to install Gradle on your machine, first check if Gradle is already installed by running gradle -v in your terminal. If the command does not return anything, then Gradle is not installed, and you can follow the instructions below.

You can install Gradle Build Tool on Linux, macOS, or Windows. The installation can be done manually or using a package manager like SDKMAN! or Homebrew.

You can find all Gradle releases and their checksums on the releases page.

Gradle runs on all major operating systems. It requires Java Development Kit (JDK) version 8 or higher to run. You can check the compatibility matrix for more information.

To check, run java -version:

Gradle uses the JDK it finds in your path, the JDK used by your IDE, or the JDK specified by your project. In this example, the $PATH points to JDK17:

You can also set the JAVA_HOME environment variable to point to a specific JDK installation directory. This is especially useful when multiple JDKs are installed:

Gradle supports Kotlin and Groovy as the main build languages. Gradle ships with its own Kotlin and Groovy libraries, therefore they do not need to be installed. Existing installations are ignored by Gradle.

See the full compatibility notes for Java, Groovy, Kotlin, and Android.

Open a console (or a Windows command prompt) and run gradle -v to run gradle and display the version, e.g.:

You can verify the integrity of the Gradle distribution by downloading the SHA-256 file (available from the releases page) and following these verification instructions.

Gradle runs on the Java Virtual Machine (JVM), which is often provided by either a JDK or JRE. A JVM version between 8 and 23 is required to execute Gradle. JVM 24 and later versions are not yet supported.

Executing the Gradle daemon with JVM 16 or earlier has been deprecated and will become an error in Gradle 9.0. The Gradle wrapper, Gradle client, Tooling API client, and TestKit client will remain compatible with JVM 8.

JDK 6 and 7 can be used for compilation. Testing with JVM 6 and 7 is deprecated and will not be supported in Gradle 9.0.

Any fully supported version of Java can be used for compilation or testing. However, the latest Java version may only be supported for compilation or testing, not for running Gradle. Support is achieved using toolchains and applies to all tasks supporting toolchains.

See the table below for the Java version supported by a specific Gradle release:

Gradle is tested with Kotlin 1.6.10 through 2.0.20-Beta2. Beta and RC versions may or may not work.

Gradle is tested with Groovy 1.5.8 through 4.0.0.

Gradle plugins written in Groovy must use Groovy 3.x for compatibility with Gradle and Groovy DSL build scripts.

Gradle is tested with Android Gradle Plugin 7.3 through 8.4. Alpha and beta versions may or may not work.

Features can be in one of four states:

Internal features are not designed for public use and are only intended to be used by Gradle itself. They can change in any way at any point in time without any notice. Therefore, we recommend avoiding the use of such features. Internal features are not documented. If it appears in this User Manual, the DSL Reference, or the API Reference, then the feature is not internal.

Internal features may evolve into public features.

Features are introduced in the incubating state to allow real-world feedback to be incorporated into the feature before making it public. It also gives users willing to test potential future changes early access.

A feature in an incubating state may change in future Gradle versions until it is no longer incubating. Changes to incubating features for a Gradle release will be highlighted in the release notes for that release. The incubation period for new features varies depending on the feature’s scope, complexity, and nature.

Features in incubation are indicated. In the source code, all methods/properties/classes that are incubating are annotated with incubating. This results in a special mark for them in the DSL and API references.

If an incubating feature is discussed in this User Manual, it will be explicitly said to be in the incubating state.

The default state for a non-internal feature is public. Anything documented in the User Manual, DSL Reference, or API reference that is not explicitly said to be incubating or deprecated is considered public. Features are said to be promoted from an incubating state to public. The release notes for each release indicate which previously incubating features are being promoted by the release.

A public feature will never be removed or intentionally changed without undergoing deprecation. All public features are subject to the backward compatibility policy.

Some features may be replaced or become irrelevant due to the natural evolution of Gradle. Such features will eventually be removed from Gradle after being deprecated. A deprecated feature may become stale until it is finally removed according to the backward compatibility policy.

Deprecated features are indicated to be so. In the source code, all methods/properties/classes that are deprecated are annotated with “@java.lang.Deprecated” which is reflected in the DSL and API References. In most cases, there is a replacement for the deprecated element, which will be described in the documentation. Using a deprecated feature will result in a runtime warning in Gradle’s output.

The use of deprecated features should be avoided. The release notes for each release indicate any features being deprecated by the release.

Gradle provides backward compatibility across major versions (e.g., 1.x, 2.x, etc.). Once a public feature is introduced in a Gradle release, it will remain indefinitely unless deprecated. Once deprecated, it may be removed in the next major release. Deprecated features may be supported across major releases, but this is not guaranteed.

Every day, a new nightly build of Gradle is created.

This contains all of the changes made through Gradle’s extensive continuous integration tests during that day. Nightly builds may contain new changes that may or may not be stable.

The Gradle team creates a pre-release distribution called a release candidate (RC) for each minor or major release. When no problems are found after a short time (usually a week), the release candidate is promoted to a general availability (GA) release. If a regression is found in the release candidate, a new RC distribution is created, and the process repeats. Release candidates are supported for as long as the release window is open, but they are not intended to be used for production. Bug reports are greatly appreciated during the RC phase.

The Gradle team may create additional patch releases to replace the final release due to critical bug fixes or regressions. For instance, Gradle 5.2.1 replaces the Gradle 5.2 release.

Once a release candidate has been made, all feature development moves on to the next release for the latest major version. As such, each minor Gradle release causes the previous minor releases in the same major version to become end-of-life (EOL). EOL releases do not receive bug fixes or feature backports.

For major versions, Gradle will backport critical fixes and security fixes to the last minor in the previous major version. For example, when Gradle 7 was the latest major version, several releases were made in the 6.x line, including Gradle 6.9 (and subsequent releases).

As such, each major Gradle release causes:

Many developers will interact with Gradle for the first time through an existing project.

The presence of the gradlew and gradlew.bat files in the root directory of a project is a clear indicator that Gradle is used.

A Gradle project will look similar to the following:

It is always recommended to execute a build with the Wrapper to ensure a reliable, controlled, and standardized execution of the build.

Depending on the operating system, you run gradlew or gradlew.bat instead of the gradle command.

Typical Gradle invocation:

To run the Wrapper on a Linux or OSX machine:

To run the Wrapper on Windows PowerShell:

The command is run in the same directory that the Wrapper is located in. If you want to run the command in a different directory, you must provide the relative path to the Wrapper:

The following console output demonstrates the use of the Wrapper on a Windows machine, in the command prompt (cmd), for a Java-based project:

The following files are part of the Gradle Wrapper:

If you want to view or update the Gradle version of your project, use the command line. Do not edit the wrapper files manually:

Consult the Gradle Wrapper reference to learn more.

The following sections describe the use of the Gradle command-line interface. Some plugins also add their own command line options.

The settings file is a script. It is either a settings.gradle file written in Groovy or a settings.gradle.kts file in Kotlin.

The Groovy DSL and the Kotlin DSL are the only accepted languages for Gradle scripts.

The settings file is typically found in the root directory of the project.

Let’s take a look at an example and break it down:

The build script is either a build.gradle file written in Groovy or a build.gradle.kts file in Kotlin.

The Groovy DSL and the Kotlin DSL are the only accepted languages for Gradle scripts.

Let’s take a look at an example and break it down:

Version catalogs provide a way to centralize your dependency declarations in a libs.versions.toml file.

The catalog makes sharing dependencies and version configurations between subprojects simple. It also allows teams to enforce versions of libraries and plugins in large projects.

The version catalog typically contains four sections:

The file is located in the gradle directory so that it can be used by Gradle and IDEs automatically. The version catalog should be checked into source control: gradle/libs.versions.toml.

To add a dependency to your project, specify a dependency in the dependencies block of your build.gradle(.kts) file.

The following build.gradle.kts file adds a plugin and two dependencies to the project using the version catalog above:

Dependencies in Gradle are grouped by configurations.

You can view your dependency tree in the terminal using the ./gradlew :app:dependencies command:

Consult the Dependency Management chapter to learn more.

All available tasks in your project come from Gradle plugins and build scripts.

You can list all the available tasks in the project by running the following command in the terminal:

The run task is executed with ./gradlew run:

In this example Java project, the output of the run task is a Hello World statement printed on the console.

Many times, a task requires another task to run first.

For example, for Gradle to execute the build task, the Java code must first be compiled. Thus, the build task depends on the compileJava task.

This means that the compileJava task will run before the build task:

Build scripts can optionally define task dependencies. Gradle then automatically determines the task execution order.

Consult the Task development chapter to learn more.

Plugins are distributed in three ways:

Applying a plugin to a project allows the plugin to extend the project’s capabilities.

You apply plugins in the build script using a plugin id (a globally unique identifier / name) and a version:

Gradle Core plugins are a set of plugins that are included in the Gradle distribution itself. These plugins provide essential functionality for building and managing projects.

Some examples of core plugins include:

Core plugins are unique in that they provide short names, such as java for the core JavaPlugin, when applied in build scripts. They also do not require versions. To apply the java plugin to a project:

There are many Gradle Core Plugins users can take advantage of.

Community plugins are plugins developed by the Gradle community, rather than being part of the core Gradle distribution. These plugins provide additional functionality that may be specific to certain use cases or technologies.

The Spring Boot Gradle plugin packages executable JAR or WAR archives, and runs Spring Boot Java applications.

To apply the org.springframework.boot plugin to a project:

Community plugins can be published at the Gradle Plugin Portal, where other Gradle users can easily discover and use them.

Custom or local plugins are developed and used within a specific project or organization. These plugins are not shared publicly and are tailored to the specific needs of the project or organization.

Local plugins can encapsulate common build logic, provide integrations with internal systems or tools, or abstract complex functionality into reusable components.

Gradle provides users with the ability to develop custom plugins using APIs. To create your own plugin, you’ll typically follow these steps:

Consult the Plugin development chapter to learn more.

An incremental build is a build that avoids running tasks whose inputs have not changed since the previous build. Re-executing such tasks is unnecessary if they would only re-produce the same output.

For incremental builds to work, tasks must define their inputs and outputs. Gradle will determine whether the input or outputs have changed at build time. If they have changed, Gradle will execute the task. Otherwise, it will skip execution.

Incremental builds are always enabled, and the best way to see them in action is to turn on verbose mode. With verbose mode, each task state is labeled during a build:

When you run a task that has been previously executed and hasn’t changed, then UP-TO-DATE is printed next to the task.

Incremental Builds are a great optimization that helps avoid work already done. If a developer continuously changes a single file, there is likely no need to rebuild all the other files in the project.

However, what happens when the same developer switches to a new branch created last week? The files are rebuilt, even though the developer is building something that has been built before.

This is where a build cache is helpful.

The build cache stores previous build results and restores them when needed. It prevents the redundant work and cost of executing time-consuming and expensive processes.

When the build cache has been used to repopulate the local directory, the tasks are marked as FROM-CACHE:

Once the local directory has been repopulated, the next execution will mark tasks as UP-TO-DATE and not FROM-CACHE.

The build cache allows you to share and reuse unchanged build and test outputs across teams. This speeds up local and CI builds since cycles are not wasted re-building binaries unaffected by new code changes.

Consult the Build cache chapter to learn more.

Gradle captures your build metadata and sends it to the Build Scan Service. The service then transforms the metadata into information you can analyze and share with others.

The information that scans collect can be an invaluable resource when troubleshooting, collaborating on, or optimizing the performance of your builds.

For example, with a build scan, it’s no longer necessary to copy and paste error messages or include all the details about your environment each time you want to ask a question on Stack Overflow, Slack, or the Gradle Forum. Instead, copy the link to your latest build scan.

To enable build scans on a gradle command, add --scan to the command line option:

You may be prompted to agree to the terms to use Build Scans.

Vist the Build Scans page to learn more.

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.

Under some circumstances, continuous build may not detect changes to inputs.

By default, the Gradle User Home (~/.gradle or C:\Users\<USERNAME>\.gradle) stores global configuration properties, initialization scripts, caches, and log files.

It can be set with the environment variable GRADLE_USER_HOME.

It is roughly structured as follows:

Consult the Gradle Directories reference to learn more.

The project root directory contains all source files from your project.

It also contains files and directories Gradle generates, such as .gradle and build.

While gradle is usually checked into source control, the build directory contains the output of your builds as well as transient files Gradle uses to support features like incremental builds.

The anatomy of a typical project root directory looks as follows:

Consult the Gradle Directories reference to learn more.

The following represents the structure of a multi-project build that contains two subprojects:

The directory structure should look as follows:

The Gradle community has two standards for multi-project build structures:

A project path has the following pattern: it starts with an optional colon, which denotes the root project.

The root project, :, is the only project in a path not specified by its name.

The rest of a project path is a colon-separated sequence of project names, where the next project is a subproject of the previous project:

You can see the project paths when running gradle projects:

Project paths usually reflect the filesystem layout, but there are exceptions. Most notably for composite builds.

You can use the gradle projects command to identify the project structure.

As an example, let’s use a multi-project build with the following structure:

Multi-project builds are collections of tasks you can run. The difference is that you may want to control which project’s tasks get executed.

The following sections will cover your two options for executing tasks in a multi-project build.

The build task is typically used to compile, test, and check a single project.

In multi-project builds, you may often want to do all of these tasks across various projects. The buildNeeded and buildDependents tasks can help with this.

In this example, the :services:person-service project depends on both the :api and :shared projects. The :api project also depends on the :shared project.

Assuming you are working on a single project, the :api project, you have been making changes but have not built the entire project since performing a clean. You want to build any necessary supporting JARs but only perform code quality and unit tests on the parts of the project you have changed.

The build task does this:

If you have just gotten the latest version of the source from your version control system, which included changes in other projects that :api depends on, you might want to build all the projects you depend on AND test them too.

The buildNeeded task builds AND tests all the projects from the project dependencies of the testRuntime configuration:

You may want to refactor some part of the :api project used in other projects. If you make these changes, testing only the :api project is insufficient. You must test all projects that depend on the :api project.

The buildDependents task tests ALL the projects that have a project dependency (in the testRuntime configuration) on the specified project:

Finally, you can build and test everything in all projects. Any task you run in the root project folder will cause that same-named task to be run on all the children.

You can run gradle build to build and test ALL projects.

Consult the Structuring Builds chapter to learn more.

Gradle builds the task graph before executing any task.

Across all projects in the build, tasks form a Directed Acyclic Graph (DAG).

This diagram shows two example task graphs, one abstract and the other concrete, with dependencies between tasks represented as arrows:

Both plugins and build scripts contribute to the task graph via the task dependency mechanism and annotated inputs/outputs.

A Gradle build has three distinct phases.

Gradle runs these phases in order:

In the initialization phase, Gradle detects the set of projects (root and subprojects) and included builds participating in the build.

Gradle first evaluates the settings file, settings.gradle(.kts), and instantiates a Settings object. Then, Gradle instantiates Project instances for each project.

In the configuration phase, Gradle adds tasks and other properties to the projects found by the initialization phase.

In the execution phase, Gradle runs tasks.

Gradle uses the task execution graphs generated by the configuration phase to determine which tasks to execute.

The settings script is either a settings.gradle file in Groovy or a settings.gradle.kts file in Kotlin.

Before Gradle assembles the projects for a build, it creates a Settings instance and executes the settings file against it.

As the settings script executes, it configures this Settings. Therefore, the settings file defines the Settings object.

The Settings object is part of the Gradle API.

Many top-level properties and blocks in a settings script are part of the Settings API.

For example, we can set the root project name in the settings script using the Settings.rootProject property:

Which is usually shortened to:

A Settings script is a series of method calls to the Gradle API that often use { …​ }, a special shortcut in both the Groovy and Kotlin languages. A { } block is called a lambda in Kotlin or a closure in Groovy.

Simply put, the plugins{ } block is a method invocation in which a Kotlin lambda object or Groovy closure object is passed as the argument. It is the short form for:

Blocks are mapped to Gradle API methods.

The code inside the function is executed against a this object called a receiver in Kotlin lambda and a delegate in Groovy closure. Gradle determines the correct this object and invokes the correct corresponding method. The this of the method invocation id("plugin") object is of type PluginDependenciesSpec.

The settings file is composed of Gradle API calls built on top of the DSLs. Gradle executes the script line by line, top to bottom.

Let’s take a look at an example and break it down:

There are many more properties and methods on the Settings object that you can use to configure your build.

It’s important to remember that while many Gradle scripts are typically written in short Groovy or Kotlin syntax, every item in the settings script is essentially invoking a method on the Settings object in the Gradle API:

Is actually:

Additionally, the full power of the Groovy and Kotlin languages is available to you.

For example, instead of using include many times to add subprojects, you can iterate over the list of directories in the project root folder and include them automatically:

Every Gradle build comprises one or more projects; a root project and subprojects.

A project typically corresponds to a software component that needs to be built, like a library or an application. It might represent a library JAR, a web application, or a distribution ZIP assembled from the JARs produced by other projects.

On the other hand, it might represent a thing to be done, such as deploying your application to staging or production environments.

Gradle scripts are written in either Groovy DSL or Kotlin DSL (domain-specific language).

A build script configures a project and is associated with an object of type Project.

As the build script executes, it configures Project.

The build script is either a *.gradle file in Groovy or a *.gradle.kts file in Kotlin.

The Project object is part of the Gradle API:

Many top-level properties and blocks in a build script are part of the Project API.

For example, the following build script uses the Project.name property to print the name of the project:

Both println statements print out the same property.

The first uses the top-level reference to the name property of the Project object. The second statement uses the project property available to any build script, which returns the associated Project object.

The Build script is composed of { …​ }, a special object in both Groovy and Kotlin. This object is called a lambda in Kotlin or a closure in Groovy.

Simply put, the plugins{ } block is a method invocation in which a Kotlin lambda object or Groovy closure object is passed as the argument. It is the short form for:

Blocks are mapped to Gradle API methods.

The code inside the function is executed against a this object called a receiver in Kotlin lambda and a delegate in Groovy closure. Gradle determines the correct this object and invokes the correct corresponding method. The this of the method invocation id("plugin") object is of type PluginDependenciesSpec.

The build script is essentially composed of Gradle API calls built on top of the DSLs. Gradle executes the script line by line, top to bottom.

Let’s take a look at an example and break it down:

A build script is made up of zero or more statements and script blocks:

Statements can include method calls, property assignments, and local variable definitions:

A script block is a method call which takes a closure/lambda as a parameter:

The closure/lambda configures some delegate object as it executes:

A build script is also a Groovy or a Kotlin script:

It can contain elements allowed in a Groovy or Kotlin script, such as method definitions and class definitions:

To make build scripts more concise, Gradle automatically adds a set of import statements to scripts.

As a result, instead of writing throw new org.gradle.api.tasks.StopExecutionException(), you can write throw new StopExecutionException() instead.

Gradle implicitly adds the following imports to each script:

Gradle provides several default tasks for a project, which are listed by running ./gradlew tasks:

Tasks either come from build scripts or plugins.

Once we apply a plugin to our project, such as the application plugin, additional tasks become available:

Many of these tasks, such as assemble, build, and run, should be familiar to a developer.

There are two classes of tasks that can be executed:

Typically, a lifecycle tasks depends on many actionable tasks, and is used to execute many tasks at once.

Let’s take a look at a simple "Hello World" task in a build script:

In the example, the build script registers a single task called hello using the TaskContainer API, and adds an action to it.

If the tasks in the project are listed, the hello task is available to Gradle:

You can execute the task in the build script with ./gradlew hello:

When Gradle executes the hello task, it executes the action provided. In this case, the action is simply a block containing some code: println("Hello world!").

The hello task from the previous section can be detailed with a description and assigned to a group with the following update:

Once the task is assigned to a group, it will be listed by ./gradlew tasks:

To view information about a task, use the help --task <task-name> command:

As we can see, the hello task belongs to the custom group.

You can declare tasks that depend on other tasks:

The dependency of taskX to taskY may be declared before taskY is defined:

The hello task from the previous example is updated to include a dependency:

The hello task now depends on the assemble task, which means that Gradle must execute the assemble task before it can execute the hello task:

Once registered, tasks can be accessed via the TaskProvider API for further configuration.

For instance, you can use this to add dependencies to a task at runtime dynamically:

Or you can add behavior to an existing task:

Here is an example of the named method being used to configure a task added by a plugin:

Gradle tasks are a subclass of Task.

In the build script, the HelloTask class is created by extending DefaultTask:

The hello task is registered with the type HelloTask.

Executing our new hello task:

Now the hello task is of type HelloTask instead of type Task.

The Gradle help task reveals the change:

Gradle provides many built-in task types with common and popular functionality, such as copying or deleting files.

This example task copies *.war files from the source directory to the target directory using the Copy built-in task:

There are many task types developers can take advantage of, including GroovyDoc, Zip, Jar, JacocoReport, Sign, or Delete, which are available in the link:DSL.

The simplest and quickest way to create a custom task is in a build script:

To create a task, inherit from the DefaultTask class and implement a @TaskAction handler:

The CreateFileTask implements a simple set of actions. First, a file called "myfile.txt" is created in the main project. Then, some text is written to the file.

A task is registered in the build script using the TaskContainer.register() method, which allows it to be then used in the build logic.

Setting the group and description properties on your tasks can help users understand how to use your task:

Once a task is added to a group, it is visible when listing tasks.

For the task to do useful work, it typically needs some inputs. A task typically produces outputs.

A task is optionally configured in a build script using the TaskCollection.named() method.

The CreateFileTask class is updated so that the text in the file is configurable:

In the named() method, we find the createFileTask task and set the text that will be written to the file.

When the task is executed:

A text file called myfile.txt is created in the project root folder:

Consult the Developing Gradle Tasks chapter to learn more.

Writing many tasks and duplicating configuration blocks in build scripts can get messy. Plugins offer several advantages over adding logic directly to the build script:

You can leverage plugins from Gradle and the Gradle community or create your own.

Plugins are available in three ways:

Plugins can be implemented as binary plugins, precompiled script plugins, or script plugins:

A plugin often starts as a script plugin (because they are easy to write). Then, as the code becomes more valuable, it’s migrated to a binary plugin that can be easily tested and shared between multiple projects or organizations.

To use the build logic encapsulated in a plugin, Gradle needs to perform two steps. First, it needs to resolve the plugin, and then it needs to apply the plugin to the target, usually a Project.

The plugins DSL is recommended to resolve and apply plugins in one step.

Gradle provides the core plugins (e.g., JavaPlugin, GroovyPlugin, MavenPublishPlugin, etc.) as part of its distribution, which means they are automatically resolved.

Core plugins are applied in a build script using the plugin name:

For example:

Non-core plugins must be resolved before they can be applied. Non-core plugins are identified by a unique ID and a version in the build file:

And the location of the plugin must be specified in the settings file:

There are additional considerations for resolving and applying plugins:

The plugin DSL provides a concise and convenient way to declare plugin dependencies.

The plugins block configures an instance of PluginDependenciesSpec:

Core Gradle plugins are unique in that they provide short names, such as java for the core JavaPlugin.

To apply a core plugin, the short name can be used:

All other binary plugins must use the fully qualified form of the plugin id (e.g., com.github.foo.bar).

To apply a community plugin from Gradle plugin portal, the fully qualified plugin id, a globally unique identifier, must be used:

See PluginDependenciesSpec for more information on using the Plugin DSL.

buildSrc is an optional directory at the Gradle project root that contains build logic (i.e., plugins) used in building the main project. You can apply plugins that reside in a project’s buildSrc directory as long as they have a defined ID.

The following example shows how to tie the plugin implementation class my.MyPlugin, defined in buildSrc, to the id "my-plugin":

The plugin can then be applied by ID:

The buildscript block is used for:

So when you want to use a library in the build script itself, you must add this library on the script classpath using buildScript:

And you can apply the globally declared dependencies in the subproject that needs it:

Binary plugins published as external jar files can be added to a project by adding the plugin to the build script classpath and then applying the plugin.

External jars can be added to the build script classpath using the buildscript{} block as described in External dependencies for the build script:

A script plugin is an ad-hoc plugin, typically written and applied in the same build script. It is applied using the legacy application method:

Let’s take a rudimentary example of a plugin written in a file called other.gradle located in the same directory as the build.gradle file:

First, import the external file using:

Then you can apply it:

Script plugins are automatically resolved and can be applied from a script on the local filesystem or remotely:

Filesystem locations are relative to the project directory, while remote script locations are specified with an HTTP URL. Multiple script plugins (of either form) can be applied to a given target.

The pluginManagement{} block is used to configure repositories for plugin resolution and to define version constraints for plugins that are applied in the build scripts.

The pluginManagement{} block can be used in a settings.gradle(.kts) file, where it must be the first block in the file:

The block can also be used in Initialization Script:

With the introduction of the plugins DSL, users should have little reason to use the legacy method of applying plugins. It is documented here in case a build author cannot use the plugin DSL due to restrictions in how it currently works.

Plugins can be applied using a plugin id. In the above case, we are using the short name "java" to apply the JavaPlugin.

Rather than using a plugin id, plugins can also be applied by simply specifying the class of the plugin:

The JavaPlugin symbol in the above sample refers to the JavaPlugin. This class does not strictly need to be imported as the org.gradle.api.plugins package is automatically imported in all build scripts (see Default imports).

When a project uses a version catalog, plugins can be referenced via aliases when applied.

Let’s take a look at a simple Version Catalog:

Then a plugin can be applied to any build script using the alias method:

A plugin is any class that implements the Plugin interface.

To create a "hello world" plugin:

Pre-compiled script plugins offer an easy way to rapidly prototype and experiment. They let you package build logic as *.gradle(.kts) script files using the Groovy or Kotlin DSL. These scripts reside in specific directories, such as src/main/groovy or src/main/kotlin.

To apply one, simply use its ID derived from the script filename (without .gradle). You can think of the file itself as the plugin, so you do not need to subclass the Plugin interface in a precompiled script.

Let’s take a look at an example with the following structure:

Our my-create-file-plugin.gradle.kts file contains the following code:

And the buildSrc build file contains the following:

The pre-compiled script can now be applied in the build.gradle(.kts) file of any subproject:

The createFileTask task from the plugin is now available in your subproject.

Convention plugins are a way to encapsulate and reuse common build logic in Gradle. They allow you to define a set of conventions for a project, and then apply those conventions to other projects or modules.

The example above has been re-written as a convention plugin as a Kotlin script called MyConventionPlugin.kt and stored in buildSrc:

The plugin can be given an id using a gradlePlugin{} block so that it can be referenced in the root:

The gradlePlugin{} block defines the plugins being built by the project. With the newly created id, the plugin can be applied in other build scripts accordingly:

A binary plugin is a plugin that is implemented in a compiled language and is packaged as a JAR file. It is resolved as a dependency rather than compiled from source.

For most use cases, convention plugins must be updated infrequently. Having each developer execute the plugin build as part of their development process is wasteful, and we can instead distribute them as binary dependencies.

There are two ways to update the convention plugin in the example above into a binary plugin.

Consult the Developing Plugins chapter to learn more.

Multi-project builds contain a single root project in a directory that Gradle views as the root path: ..

Subprojects are located physically under the root path: ./subproject.

A subproject has a path, which denotes the position of that subproject in the multi-project build. In most cases, the project path is consistent with its location in the file system.

The project structure is created in the settings.gradle(.kts) file. The settings file must be present in the root directory.

Let’s look at a basic multi-project build example that contains a root project and a single subproject.

The root project is called basic-multiproject, located somewhere on your machine. From Gradle’s perspective, the root is the top-level directory ..

The project contains a single subproject called ./app:

This is the recommended project structure for starting any Gradle project. The build init plugin also generates skeleton projects that follow this structure - a root project with a single subproject:

The settings.gradle(.kts) file describes the project structure to Gradle:

In this case, Gradle will look for a build file for the app subproject in the ./app directory.

You can view the structure of a multi-project build by running the projects command:

In this example, the app subproject is a Java application that applies the application plugin and configures the main class. The application prints Hello World to the console:

You can run the application by executing the run task from the application plugin in the project root:

In the settings file, you can use the include method to add another subproject to the root project:

The include method takes project paths as arguments. The project path is assumed to be equal to the relative physical file system path. For example, a path services:api is mapped by default to a folder ./services/api (relative to the project root .).

More examples of how to work with the project path can be found in the DSL documentation of Settings.include(java.lang.String[]).

Let’s add another subproject called lib to the previously created project.

All we need to do is add another include statement in the root settings file:

Gradle will then look for the build file of the new lib subproject in the ./lib/ directory:

To further describe the project architecture to Gradle, the settings file provides project descriptors.

You can modify these descriptors in the settings file at any time.

To access a descriptor, you can:

Using this descriptor, you can change the name, project directory, and build file of a project:

Consult the ProjectDescriptor class in the API documentation for more information.

Let’s take a hypothetical project with the following structure:

If your settings.gradle(.kts) looks like this:

Gradle sees a subproject with a logical project name of :subs:web:my-web-module and two, possibly unintentional, other subprojects logically named :subs and :subs:web. This can lead to phantom build directories, especially when using allprojects{} or subproject{}.

To avoid this, you can use:

So that you only end up with a single subproject named :my-web-module.

So, while the physical project layout is the same, the logical results are different.

As your project grows, naming and consistency get increasingly more important. To keep your builds maintainable, we recommend the following:

Let’s explore a theoretical multi-project build with the following layout:

In this example, there are three subprojects called shared, api, and person-service:

We use the : separator to define a project path such as services:person-service or :shared. Consult the DSL documentation of Settings.include(java.lang.String[]) for more information about defining project paths.

A project dependency affects execution order. It causes the other project to be built first and adds the output with the classes of the other project to the classpath. It also adds the dependencies of the other project to the classpath.

If you execute ./gradlew :api:compile, first the shared project is built, and then the api project is built.

Sometimes, you might want to depend on the output of a specific task within another project rather than the entire project. However, explicitly declaring a task dependency from one project to another is discouraged as it introduces unnecessary coupling between tasks.

The recommended way to model dependencies, where a task in one project depends on the output of another, is to produce the output and mark it as an "outgoing" artifact. Gradle’s dependency management engine allows you to share arbitrary artifacts between projects and build them on demand.

buildSrc is a Gradle-recognized and protected directory which comes with some benefits:

The buildSrc directory is treated as an included build.

For multi-project builds, there can be only one buildSrc directory, which must be in the root project directory.

buildSrc uses the same source code conventions applicable to Java, Groovy, and Kotlin projects. It also provides direct access to the Gradle API.

A typical project including buildSrc has the following layout:

In the buildSrc, the build script shared.gradle(.kts) is created. It contains dependencies and other build information that is common to multiple subprojects:

In the buildSrc, the MyCustomTask is also created. It is a helper task that is used as part of the build logic for multiple subprojects:

The MyCustomTask task is used in the build script of the api and shared projects. The task is automatically available because it’s part of buildSrc.

The shared.build(.kts) file is also applied:

Gradle’s recommended way of organizing build logic is to use its plugin system.

We can write a plugin that encapsulates the build logic common to several subprojects in a project. This kind of plugin is called a convention plugin.

While writing plugins is outside the scope of this section, the recommended way to build a Gradle project is to put common build logic in a convention plugin located in the buildSrc.

Let’s take a look at an example project:

This build contains three subprojects:

The source code for the convention plugin created in the buildSrc directory is as follows:

For the convention plugin to compile, basic configuration needs to be applied in the build file of the buildSrc directory:

The convention plugin is applied to the api, shared, and person-service subprojects:

An improper way to share build logic between subprojects is cross-project configuration via the subprojects {} and allprojects {} DSL constructs.