Plugins Overview

Every build tool of this section has an extension mechanism, and they differ in how much of the tool itself is an extension.

The equivalent pages are Ant: Antlibs & Namespaces, Ant: Writing Custom Tasks, Maven: Plugins & Their Configuration, Maven: Extensions and Maven: Writing Plugins; the three philosophies side by side are on Comparing Ant, Maven & Gradle. The most visible difference for a reader coming from Maven is that a Gradle plugin is applied, not bound: applying java does not decide when anything runs, it only makes tasks such as compileJava exist, and the task graph decides the order.

Gradle’s documentation distinguishes where a plugin comes from, and separately how a local plugin is written.

Source: Gradle User Manual: Sources for Plugins and Gradle User Manual: Types of Plugins

The examples use the tidepool toolkit of this section: a tidepool-model library, a tidepool-engine library that reads station data with Apache Commons CSV, and a tidepool-cli command line application built on picocli. The sources are the same as in the rest of the section; only the build scripts are shown, because they are what plugins are about. The build starts with the smallest useful set of plugins: the core plugins java-library and application, one community plugin from the Plugin Portal (io.github.ben-manes.versions, 0.66.0 on 2026-10-16, which adds a dependencyUpdates report task) and one settings plugin (the Foojay toolchains resolver, 1.0.0).

tidepool-model/build.gradle(.kts) contains only java-library (Kotlin) or id 'java-library' (Groovy) in its plugins { } block, and tidepool-cli/build.gradle(.kts) applies application, depends on project(":tidepool-engine") and info.picocli:picocli:4.7.7, and sets application { mainClass = "io.tidepool.cli.Main" }. Building the whole thing with both DSLs gave (task lines trimmed; their order is not fixed):

A second ./gradlew build reported 9 actionable tasks: 9 up-to-date and Configuration cache entry reused., so the build, including the community plugin, is configuration cache compatible. The Plugin Portal page of the plugin carries the same statement as a "CC-compatible" badge (and one for Isolated Projects, see Configuration Cache & Isolated Projects); a plugin that is not compatible makes the whole build incompatible, whatever your own scripts do. Running the application, ./gradlew -q :tidepool-cli:run --args="../data/stations.csv SF", printed San Francisco: -0,869 m in both DSLs (the decimal comma is the default locale of the machine that ran it).

The sections below take this build apart: which plugins are core, what the Portal is, what plugins { } accepts, what pluginManagement { } adds, and the older ways.

A core plugin is a plugin of the distribution. It has a short id (java, application) that is a shorthand for the id in the org.gradle namespace (org.gradle.java), and Gradle never downloads it. Because it is versioned with Gradle, it cannot carry a version of its own, and Gradle says so:

The same error text appeared for id("java-library") version "1.0" in the Kotlin DSL and id 'java-library' version '1.0' in the Groovy DSL. The reverse mistake, apply false on a core plugin in the root script (a habit copied from community plugins), is also rejected:

The Groovy DSL printed the same message with the id shown as java-library. The second message also explains why core plugins need no repository: they are on the Gradle classpath from the start.

The plugin reference of the user manual lists the core plugins by purpose. The table groups the 42 ids that apply to a project; each id was applied to a project of its own in a scratch build (one plugins { id("...") } per project, ./gradlew --continue help) and every one resolved on Gradle 9.8.1 on macOS. That a plugin applies does not mean it is useful on the machine: the native ones need a C++ or Swift toolchain to build anything.

Besides these, the reference lists jvm-toolchain-management, which is a settings plugin that configures where JDKs are downloaded from (the Foojay plugin of the example builds on it). Several plugins on the list apply others: java-library and application both apply java, and the lifecycle tasks clean, assemble, check and build come from the lifecycle plugin that base builds on. The next section shows how to see the complete result of applying a few plugins, which is much longer than the plugins named in the script. The documentation of each plugin has its own page: the Java plugins are on Java Projects, testing and reports on Testing JVM Projects, maven-publish and signing on Publishing, java-gradle-plugin on Binary Plugins, and build-init and wrapper on Installation and Gradle Wrapper.

Core plugins also leave the distribution over time. The maven plugin and uploadArchives were removed in Gradle 7.0, and FindBugs, JDepend, the build announcements plugins, the build comparison plugin and the JavaScript plugins were removed in 6.0; the replacements (SpotBugs, maven-publish) are community plugins or newer core plugins. The table at the end of the page lists the plugins that Gradle in Action (written for Gradle 1.7) uses and that no longer exist.

Source: Gradle User Manual: Gradle Core Plugins Reference and Gradle User Manual: Core plugins

A community plugin is any non-core plugin that a repository serves. The usual repository is the Gradle Plugin Portal, https://plugins.gradle.org/, a searchable catalogue of plugins with one page per plugin and version. A plugin page has everything needed to use the plugin: the id, the author, the source link, the versions with their release dates, the Gradle features the plugin declares compatibility with (configuration cache, Isolated Projects), and ready-made snippets for the plugins { } block, for a buildSrc/convention-plugin dependency and for the legacy buildscript form. The Portal is also a Maven-layout repository at https://plugins.gradle.org/m2/, which is what the gradlePluginPortal() function of a repository block means, and it can be mirrored by an artifact repository manager (the Portal documentation says to mirror Central as well, because plugins have dependencies there, and to allow plugins-artifacts.gradle.org, where the artifact downloads are redirected). Publishing to the Portal is described on Testing & Publishing Plugins.

When a plugins { } entry is processed, Gradle looks for the id in an order that the "not found" error spells out: the core plugins, then the plugins defined by included builds (and buildSrc), then the plugin repositories.

A request for a plugin that a parent project or the settings has already put on the classpath is a separate case: the same version, or no version, reuses it, and a different version is an error (shown below).

The "not found" error lists the three sources. For an id that does not exist and has no version, the repositories line says why it could not look:

With a version the repositories are searched, and the message shows the marker coordinates that were looked up and the repositories that were consulted (the example build had the Plugin Portal, printed as "Gradle Central Plugin Repository", and Maven Central, printed as "MavenRepo", in its pluginManagement). It is the same text in both DSLs:

The plugins { } block is the recommended way to apply a plugin: the user manual’s best practices say to always use it. Because the block can only contain a restricted form, Gradle can read it before running the rest of the script and resolve the plugins early, and the Kotlin DSL can generate type-safe accessors for what they add (see Kotlin DSL and the description of the block on Settings & Build Scripts). The permitted forms are:

The syntax is deliberately constrained. The id and the version must be constant string literals, so a variable, a property or a function call is rejected; the block must be a top-level statement of the script, so an if or loop around it is rejected; and it is available only in the build scripts and settings scripts of a build, not in script plugins or init scripts. The constraint is what makes the block "idempotent and side effect free", and the escape for a version that has to come from a property is pluginManagement, below. These restrictions let Gradle optimise the loading and reuse of plugin classes and tell editors what the plugins add to the script. The statement about position differs between the two languages: in the Groovy DSL any other statement before plugins { } is a compile error (the exact message is on the Settings & Build Scripts page), in the Kotlin DSL a group = "..." before the block compiled and ran. Keep plugins { } first in both.

Nesting is rejected differently in each language. In the Kotlin DSL (if (true) { plugins { `java-library` } }):

In the Groovy DSL the same nesting is not even recognised as a block, and Groovy looks for an ordinary method called plugins:

(The closure name in the message is generated and differs on every run.)

Source: Gradle User Manual: The plugins block, Gradle User Manual: Limitations of the plugins DSL and Gradle User Manual: Apply Plugins Using the plugins Block

pluginManagement { } in the settings file is the configuration point for everything about finding plugins: where the repositories are, which versions plugins get, and how an id maps to an artifact. It must be the first block of the settings script (the earlier page shows the error for the wrong order). Without it, plugins resolve from the Gradle Plugin Portal only; the example lists the Portal and Maven Central because some plugins and some of their dependencies are published only to Central. The block also exists for init scripts, inside settingsEvaluated { } (not run here).

Before the plugins { } block (introduced in Gradle 2.1, together with the Plugin Portal), a build listed the plugin as a dependency of the build script and then applied it. The form still works and is documented as legacy. Here is the engine of the example written that way:

Both versions built :tidepool-engine and listed dependencyUpdates. The differences from the plugins { } block are the point of avoiding it:

The legacy form is still the right tool in two situations: a library needed by the build script itself (a YAML or JSON parser used in the script body), which belongs in buildscript { dependencies { classpath(...) } }, and a script plugin applied with apply(from = "other.gradle.kts"), where a plugins { } block is not allowed. Note that apply(plugin = "...") also takes a class, apply<JavaPlugin>() in the Kotlin DSL and apply plugin: JavaPlugin in Groovy.

Source: Gradle User Manual: Applying plugins using the buildscript block, Gradle User Manual: Legacy Plugin Application and Gradle User Manual: Script plugins

A plugin is a class with one method, apply(target), and the type of target decides where it can be applied. Gradle has three scopes:

For a precompiled script plugin the scope comes from the file name: name.gradle.kts is a project plugin, name.settings.gradle.kts is a settings plugin and name.init.gradle.kts is an init plugin (and the same with .gradle for the Groovy DSL). A file called name.gradle.kts is a project plugin even if a settings script applies it. The settings plugin of the running example, the Foojay resolver, was shown in the settings plugins { } block and its failure when applied to a project above. See Settings & Build Scripts for what a settings script can do.

An init script can apply a plugin to every project of every build it is used with, which is how an organisation enforces a convention or a report without touching the repositories. The example applies the core project-report plugin, whose projectReport task writes reports about the project, to all projects, from a file that is not part of the project:

Passed with -I, in both DSLs and with the configuration cache on, ./gradlew -q -I reports.init.gradle.kts :tidepool-model:tasks --group=reporting printed:

(the Groovy script printed the same). Without -I the same command printed No tasks for the group. The -I option is a one-off; a script in init.d of the Gradle User Home applies to every build of the user. The location and the init script lifecycle are on Init Scripts & the Tooling API and Directories & Logging.

Source: Gradle User Manual: Scope of Plugins

A plugin does not have to be published. The directory buildSrc, next to settings.gradle(.kts), is built before the rest of the build and its output goes on the classpath of every build script; a precompiled script plugin placed there is available by id. The example adds a tiny plugin, tidepool.stamp, which registers a stamp task in the tidepool group. It is a script in the build DSL; the file name is the plugin id.

tidepool-model/build.gradle(.kts) then applies it by id:

./gradlew -q :tidepool-model:stamp printed stamped by tidepool-model in both DSLs, and :tidepool-model:tasks --group=tidepool listed stamp under "Tidepool tasks". The configuration cache was on and the second run reused the entry, so the plugin is compatible: it copies project.name into a local value at configuration time and not inside doLast, which is the pattern of the previous sections. buildSrc is a separate build with its own repositories. The Kotlin variant needs one even though the kotlin-dsl plugin id resolves without it, because the plugin compiles the scripts against Kotlin libraries: without the repositories { gradlePluginPortal() } block of the example, the run failed with

(the output continued with the same message for kotlin-reflect). The Groovy variant, groovy-gradle-plugin, ran without a repository block. Two limitations of the plugin id are documented: it cannot start with org.gradle and it cannot equal a core plugin id.

buildSrc is the simplest place for build logic and has a cost: any change in it makes the entire build out of date. An included build, for example build-logic, added with pluginManagement { includeBuild("build-logic") }, holds the same precompiled script plugins with fewer invalidations, and the user manual’s best practices name it as the preferred location of build logic, in particular of convention plugins. Standalone binary plugins, written as classes, are on Binary Plugins. Both are covered on Convention Plugins & Sharing Build Logic.

Source: Gradle User Manual: Precompiled script plugins, Gradle User Manual: Applying convention plugins from the buildSrc directory and Gradle User Manual: Favor build-logic Composite Builds for Build Logic

The user manual has a reference page that lists each core plugin with a one-line description and a link, grouped as in the table above; the Gradle DSL reference documents the extension and task types a plugin adds, and the Javadoc documents the plugin classes. The sibling pages of this section that describe particular plugins are listed in the previous sections. For a community plugin the documentation is the Portal page and the plugin’s own repository, and the plugins { } snippet on its Portal page is the authoritative id and version to copy.

The plugin DSL is old and stable, so most of this page applies unchanged to Gradle 8.14, the last 8.x minor (not run here: 8.14 was not available). From the release notes of the versions that introduced each feature: the plugins { } block and the Plugin Portal arrived in Gradle 2.1; the pluginManagement { } block and plugin resolution rules in 3.5 (replacing pluginRepositories in the settings file); and pluginManagement { plugins { } }, with versions read from gradle.properties, in 5.6. Plugin version catalog aliases came with version catalogs (stable in 7.4). What Gradle 9.0 changed for plugins is mostly about the plugins themselves: it removed APIs that 8.x had deprecated (among them conventions, Project.exec/javaexec and the "name"() task syntax), runs on JVM 17 or later, embeds Kotlin 2.2 and Groovy 4, and requires Kotlin Gradle plugin 2.0.0 or newer. A community plugin that has not been updated since 8.x can therefore fail on 9.x with messages that point at the plugin’s code, and the remedy is to upgrade the plugin (the second reason to prefer plugins that declare their compatibility), or to replace it. The by settings, by project and by extra property delegates that many pluginManagement examples used are deprecated from 9.6 (see above). The matrix of what runs where is on Versions, Compatibility & Release History and the upgrade path on Upgrading Gradle.

Source: Gradle 2.1 Release Notes, Gradle 3.5 Release Notes, Gradle 5.6 Release Notes and Gradle 9.0.0 Release Notes

Gradle in Action (Muschko, Manning, 2014) was written for Gradle 1.7, before the Plugin Portal existed, and its plugin chapters reflect that. Current status of the statements about plugins, from the official documentation: