The Checkstyle Plugin

The Checkstyle plugin performs quality checks on your project’s Java source files using Checkstyle and generates reports from these checks.

Usage

To use the Checkstyle plugin, include the following in your build script:

build.gradle.kts

plugins {
    checkstyle
}

build.gradle

plugins {
    id 'checkstyle'
}

The plugin adds a number of tasks to the project that perform the quality checks. You can execute the checks by running gradle check.

Note that, by default, Checkstyle runs with the same Java version used to run Gradle, or with the project’s Java toolchain if one is configured. To run Checkstyle on a specific JDK regardless, see Configuring Checkstyle with Java Toolchains.

Tasks

The Checkstyle plugin adds the following tasks to the project:

checkstyleMain — Checkstyle: Depends on: classes

Runs Checkstyle against the production Java source files.
checkstyleTest — Checkstyle: Depends on: testClasses

Runs Checkstyle against the test Java source files.
checkstyleSourceSet — Checkstyle: Depends on: sourceSetClasses

Runs Checkstyle against the given source set’s Java source files.

Dependencies added to other tasks

The Checkstyle plugin adds the following dependencies to tasks defined by the Java plugin.

check: Depends on: All Checkstyle tasks, including checkstyleMain and checkstyleTest.

Project layout

By default, the Checkstyle plugin expects configuration files to be placed in the root project, but this can be changed.

<root>
└── config
    └── checkstyle           (1)
        └── checkstyle.xml   (2)
        └── suppressions.xml

1	Checkstyle configuration files go here
2	Primary Checkstyle configuration file

Dependency management

The Checkstyle plugin adds the following dependency configurations:

Table 1. Checkstyle plugin - dependency configurations
Name	Meaning
`checkstyle`	The Checkstyle libraries to use

By default, the checkstyle configuration uses com.puppycrawl.tools:checkstyle. The version of com.puppycrawl.tools:checkstyle used is derived from the extension’s tool version, which defaults to 10.24.0. You can override it:

checkstyle {
    toolVersion = "10.24.0"
}

If another dependency is added, the default com.puppycrawl.tools:checkstyle dependency will be removed:

build.gradle.kts

checkstyle {
    toolVersion = "10.12.4"
}

dependencies {
    checkstyle("group:artifact:version")
}

build.gradle

checkstyle {
    toolVersion = '10.12.4'
}

dependencies {
    checkstyle 'group:artifact:version'
}

To add a dependency to the checkstyle configuration while also retaining a dependency on com.puppycrawl.tools:checkstyle, use the following solution:

build.gradle.kts

checkstyle {
    toolVersion = "10.12.4"
}

dependencies {
    checkstyle("com.puppycrawl.tools:checkstyle:${checkstyle.toolVersion}")
    checkstyle("group:artifact:version")
}

build.gradle

checkstyle {
    toolVersion = '10.12.4'
}

dependencies {
    checkstyle "com.puppycrawl.tools:checkstyle:${checkstyle.toolVersion}"
    checkstyle 'group:artifact:version'
}

Configuration

The Checkstyle plugin is configured through the CheckstyleExtension (the checkstyle {} block). The most commonly used properties and their default values are:

Table 2. Gradle defaults for Checkstyle properties
Property	Description	Gradle default
`toolVersion`	The version of Checkstyle to use.	`10.24.0`
`configDirectory`	Directory containing the Checkstyle configuration files (exposed as `config_loc`).	`config/checkstyle` (relative to the root project)
`config`	The Checkstyle configuration to use.	`checkstyle.xml` in `configDirectory`
`configProperties`	Properties substituted into the configuration file.	(empty)
`maxErrors`	The maximum number of errors allowed before failing the build.	`0`
`maxWarnings`	The maximum number of warnings allowed before failing the build.	`Integer.MAX_VALUE` (unlimited)
`showViolations`	Whether rule violations are shown on the console.	`true`
`enableExternalDtdLoad`	Whether to allow loading external DTD files referenced from the configuration (disabled by default for security).	`false`
`reportsDirectory`	The directory where reports are generated.	`layout.buildDirectory.dir("reports/checkstyle")`

See the CheckstyleExtension class in the API documentation for comprehensive configuration options.

Configuring Checkstyle with Java Toolchains

Checkstyle’s minimum required JDK depends on its version: the default version (10.24.0) requires JDK 11, while Checkstyle 13.0.0 and later require JDK 21. For projects targeting earlier JDK versions, such as JDK 8, this presents a compatibility challenge. Historically, users have resorted to backport dependencies (e.g., com.puppycrawl.tools:checkstyle-backport-jre8) to bridge this gap. However, as both Checkstyle and Gradle align with modern Java versions, a more robust and future-proof solution is available through Gradle’s Java toolchains.

By leveraging the javaLauncher property, you can explicitly configure Checkstyle tasks to execute with a designated JDK version, independent of the JDK used for your project’s compilation or Gradle’s runtime. The following configuration ensures that Checkstyle operates with JDK 17:

tasks.withType(Checkstyle).configureEach {
    javaLauncher = javaToolchains.launcherFor {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

This approach offers several advantages:

Decoupling: Checkstyle execution is isolated from the project’s JDK, enabling compatibility without altering your build’s core environment.
Automation: Gradle’s toolchain support automatically provisions the specified JDK, streamlining setup and ensuring consistency across environments.
Sustainability: It eliminates reliance on community-maintained backports, which may lag behind official releases or introduce maintenance overhead.

We strongly recommend adopting this configuration as the preferred method for managing Checkstyle’s JDK requirements, particularly as the ecosystem progresses toward newer JDK versions.

Built-in variables

The Checkstyle plugin defines a config_loc property that can be used in Checkstyle configuration files to define paths to other configuration files like suppressions.xml.

checkstyle.xml

<module name="SuppressionFilter">
    <property name="file" value="${config_loc}/suppressions.xml"/>
</module>

Customizing the HTML report

The HTML report generated by the Checkstyle task can be customized using a XSLT stylesheet, for example to highlight specific errors or change its appearance:

build.gradle.kts

tasks.withType<Checkstyle>().configureEach {
    reports {
        xml.required = false
        html.required = true
        html.stylesheet = resources.text.fromFile("config/xsl/checkstyle-custom.xsl")
    }
}

build.gradle

tasks.withType(Checkstyle) {
    reports {
        xml.required = false
        html.required = true
        html.stylesheet = resources.text.fromFile('config/xsl/checkstyle-custom.xsl')
    }
}

View a sample Checkstyle stylesheet.

Generate SARIF report

SARIF report is supported on Checkstyle versions 10.3.3 and newer. It is not enabled by default.

build.gradle.kts

checkstyle {
    toolVersion = "10.3.3"
}
tasks.withType<Checkstyle>().configureEach {
    reports {
        sarif.required = true
    }
}

build.gradle

checkstyle {
    toolVersion = '10.3.3'
}
tasks.withType(Checkstyle) {
    reports {
        sarif.required = true
    }
}

Changing the amount of memory given to Checkstyle

Checkstyle analysis is performed in a separate process. By default, the Checkstyle process is given a max heap of 512MB. When analyzing many source files, you may need to provide additional memory to this process. You can change the amount of memory for Checkstyle by configuring the Checkstyle.maxHeapSize.

build.gradle.kts

tasks.withType<Checkstyle>().configureEach {
    minHeapSize = "200m"
    maxHeapSize = "1g"
}

build.gradle

tasks.withType(Checkstyle) {
    minHeapSize = "200m"
    maxHeapSize = "1g"
}