Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Plugins

Gradle Plugins: What They Are and How to Apply Them

Learn what Gradle plugins do, how the plugins block works, the difference between core, community and local plugins, plugin IDs, versions, apply false and the Plugin Portal.

Gradle itself knows very little about Java, Kotlin, Android or Docker. It only knows how to run tasks in the right order. Everything else, such as compiling code, running tests or building a container image, comes from plugins. A plugin is a piece of reusable build logic that adds tasks, configuration, conventions and extensions to a project when you apply it.

This lesson shows what a plugin really does, how you apply one with the plugins {} block, where plugins come from, and how to keep versions sane. Chapter 5 continues with the Java plugins and writing your own plugin.

Honesty note. The Gradle tool cannot run inside this website. The build files in this chapter are real and shown read-only. Wherever an idea can be shown in plain code, we give a small, clearly labelled Java stand-in that runs on the site. A stand-in teaches the concept; it is not Gradle.

What a plugin does

When you write id("java") in a build script, Gradle finds the plugin with that ID and calls its apply(project) method. The plugin may then:

  • register tasks (compileJava, test, jar),
  • create configurations for dependencies (implementation, testImplementation),
  • add extensions, the blocks you can write in the script (java { ... }),
  • set conventions, default values such as src/main/java as the source folder,
  • react to other plugins being applied.

So a plugin is just code that configures a project. Applying java turns an empty project into one that knows how to compile Java.

The plugins block

The recommended way to apply a plugin is the plugins {} block at the top of build.gradle.kts (or build.gradle):

Kotlin
plugins {
    java                                   // core plugin, short name
    id("application")                      // core plugin, by ID
    id("org.springframework.boot") version "3.4.1"   // community plugin
    id("io.spring.dependency-management") version "1.1.7"
}
GROOVY
plugins {
    id 'java'
    id 'application'
    id 'org.springframework.boot' version '3.4.1'
}

Three kinds of plugins appear here:

Kind Example Needs a version?
Core plugin, shipped with Gradle java, application, maven-publish, jacoco No, it matches the Gradle version
Community plugin from the Plugin Portal org.springframework.boot, com.github.johnrengelman.shadow Yes
Local plugin (your buildSrc or included build) my.conventions No

The plugins {} block is special. Gradle reads it before the rest of the script, so it can fetch plugins and put them on the build's classpath early. That is why it must be the first block (only buildscript {}, pluginManagement {} and comments may come before it) and why you cannot use ordinary variables inside it.

Where plugins are found

Gradle resolves a plugin ID with a version from plugin repositories. By default that is the Gradle Plugin Portal. You can change this in settings.gradle.kts:

Kotlin
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
        maven { url = uri("https://repo.example.com/plugins") }
    }
}

Putting the repositories in pluginManagement applies to every project of the build. Note that repositories {} in a project's own build script is for dependencies of your code, not for plugins. Mixing these up is one of the most common beginner errors; see dependency repositories in chapter 4.

apply false and version control

In a multi-project build you often want every subproject to use the same plugin version without applying it to the root. Use apply false in the root and apply the plugin by ID (no version) in the subprojects:

Kotlin
// root build.gradle.kts
plugins {
    id("org.jetbrains.kotlin.jvm") version "2.1.0" apply false
}
Kotlin
// app/build.gradle.kts
plugins {
    id("org.jetbrains.kotlin.jvm")   // version comes from the root
}

A second approach is to declare versions once in pluginManagement { plugins { ... } } in settings.gradle.kts, or in a version catalog with alias(libs.plugins.kotlin). Whatever you pick, keep one place that knows the version.

The legacy apply syntax

Older builds use apply plugin: 'java' or apply(plugin = "java"). It still works, but it cannot download plugins by itself, it hides which plugins are used, and Gradle cannot optimize around it. Use plugins {} for new work. You will meet the legacy form when migrating, which chapter 8 covers.

A stand-in: a plugin is code that configures a project

Here is the idea in plain Java. A Project holds tasks; a Plugin receives the project and adds to it. Applying two plugins just calls apply twice.

Java Stand-in: plugins configure a project (not Gradle)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The real application plugin applies the java plugin itself. You can see that relationship by changing the order in main: the stand-in throws because the second plugin depends on the first.

Listing what a plugin gave you

In a real project, three commands show what applying plugins produced:

TEXT
./gradlew tasks --all          # every task, including those from plugins
./gradlew dependencies         # configurations and their resolved libraries
./gradlew properties           # project properties and conventions

tasks --all is the quickest way to learn a new plugin: apply it, run the command, and read the new entries.

Plugin conflicts and ordering

Plugins are applied in the order written. If plugin B needs plugin A's extension, A must come first or B must apply A itself. When two plugins both register a task with the same name, the build fails with an error naming the task. The fix is to apply only one, or to rename a task in your script.

Java Stand-in: ordering matters

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main job of a Gradle plugin?

    A plugin's apply method configures a project. It registers tasks, creates dependency configurations, adds extensions and sets defaults.
  2. 2. Which plugin needs NO version in the plugins block?

    Core plugins ship with Gradle, so their version is the Gradle version. Community plugins need a version so Gradle can resolve them from a plugin repository.
  3. 3. Why is a plugin repository declared in pluginManagement in settings.gradle.kts?

    pluginManagement controls where plugins are resolved from for every project. The repositories block in a project's script is for the code's dependencies.
  4. 4. What does apply false do in a root plugins block?

    apply false makes the plugin version known to the build so subprojects can apply it by ID without a version, while the root project itself stays unconfigured.

Summary

  • A plugin is code that configures a project: tasks, configurations, extensions and conventions.
  • Apply plugins with the plugins {} block; use id("...") version "..." for community plugins.
  • Core plugins need no version; community plugins come from the Plugin Portal or repositories listed in pluginManagement.
  • apply false centralizes plugin versions in the root of a multi-project build.
  • ./gradlew tasks --all shows what a plugin added.

Next: The Java, Java Library and Application plugins