Plugin Introduction

A Gradle plugin is an add-on that enhances your build by adding tasks, applying conventions, or enabling specific configurations.

Plugins lets you extend and organize build logic in a modular and reusable way.

You apply plugins using the plugins block:

build.gradle.kts

plugins {
    id("org.springframework.boot") version "3.3.1"
}

build.gradle

plugins {
    id 'org.springframework.boot' version '3.3.1'
}

When you apply a plugin, it typically does one or both of the following:

Adds tasks to your build - Plugins often expose tasks that perform a specific action.

For example, the Maven Publish Plugin adds a publishToMavenLocal task, which uploads artifacts to a local Maven repository.
Applies behavior and conventions - Some plugins automatically configure parts of your build when applied.

For example, the Java Plugin creates the main and test source sets and applies sensible defaults for compiling and testing Java code.

Most plugins provide DSL blocks you can use to fine-tune their behavior in build scripts. For instance, the Java plugin lets you configure how tests are run using the test task:

build.gradle.kts

tasks.withType<Test>().configureEach {
    useJUnitPlatform {
        includeEngines("junit-vintage")
        // excludeEngines("junit-jupiter")
    }
}

build.gradle

tasks.withType(Test).configureEach {
    useJUnitPlatform {
        includeEngines 'junit-vintage'
        // excludeEngines 'junit-jupiter'
    }
}

And Java options using the java {} block:

build.gradle.kts

java {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
}

build.gradle

java {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
}

Plugin Types

Gradle supports three types of plugins, each applied at a different phase of the build lifecycle. Init, Settings, and Project plugins. The most common and popular plugins are Project plugins.

1. Init Plugins

Applied globally to all builds. Loaded from ~/.gradle/init.gradle[.kts] or passed via the --init-script command-line option.
Configure the Gradle runtime before the build even starts. Useful for enforcing corporate policies, setting up shared CI configuration, or applying global conventions.
Implement the Plugin<Gradle> interface.

2. Settings Plugins

Applied in settings.gradle[.kts] files.
Configure the build layout, such as which projects are included or how plugins are resolved.
Implement the Plugin<Settings> interface.

3. Project Plugins

Applied in build.gradle[.kts] files.
Configure tasks, dependencies, and project-specific behavior.
Implement the Plugin<Project> interface.

Plugin Scope

The scope of a plugin is determined by the interface it implements. The scope determines where the plugin can be applied and what parts of the Gradle lifecycle it can modify. Each scope gives you access to different configuration APIs.

Each plugin type is defined by the interface it implements and the stage of the build lifecycle where it applies:

Plugin Type Interface Scope Applied In

Plugin Type	Interface	Scope	Applied In
Init Plugin	`Plugin<Gradle>`	Global	`init.gradle[.kts]` or `--init-script`
Settings Plugin	`Plugin<Settings>`	Build Layout	`settings.gradle[.kts]`
Project Plugin	`Plugin<Project>`	Per-Project	`build.gradle[.kts]`

Init Plugin

Plugin<Gradle>

Global

init.gradle[.kts] or --init-script

Settings Plugin

Plugin<Settings>

Build Layout

settings.gradle[.kts]

Project Plugin

Plugin<Project>

Per-Project

build.gradle[.kts]

Plugin Sources

Gradle plugins come from three different places, the Gradle distribution itself, external community sources, or your own internal builds.

1. Core Plugins

Bundled with Gradle itself (e.g., java, application).
You don’t author or publish them, they’re built-in.

2. Community Plugins

Created and published by the community.
Typically hosted on the Gradle Plugin Portal.
Distributed as binary JARs.

3. Local Plugins

Custom plugins you write yourself, for your own builds.
Useful for sharing logic across subprojects or internal builds.

Authoring Plugins

Gradle provides two main ways to create your own custom plugins. This is code you write to extend Gradle’s capabilities and modularize your build logic.

1. Precompiled Script Plugins

Written as .gradle.kts or .gradle files.
Compiled automatically during the build.
Ideal for bundling simple conventions.

2. Binary Plugins

Typically written in Java, Kotlin, or Groovy.
Packaged as JARs and reusable across multiple builds.
Can be published to repositories for sharing.

Next Step: Learn about Pre-Compiled Script Plugins >>