GitHub Twitter Stackoverflow GoogleGroups JProfiler

Get Started with Checkstyle

On This Page

Run Checkstyle on a Java project and see your first result in a few minutes.

Checkstyle needs two things: Java source code to analyze and a configuration that defines the checks to apply. This guide starts with one simple check so you can verify that everything is working before choosing a complete coding standard.

Before you begin, make sure your Java runtime is supported by the Checkstyle version you are using. See JRE and JDK compatibility for details.

1. Add a starter configuration

Every Checkstyle run uses a configuration file that defines which checks are enabled.

Create config/checkstyle/checkstyle.xml:

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
  "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
  "https://checkstyle.org/dtds/configuration_1_3.dtd">

<module name="Checker">
  <module name="TreeWalker">
    <module name="AvoidStarImport"/>
  </module>
</module>

This deliberately enables only AvoidStarImport, which reports wildcard imports such as: 

import java.util.*;

The configuration is intentionally small so that the first setup is easy to understand. It is not intended to be a complete coding standard. After Checkstyle is running, you can adopt one of the supplied style configurations or add the checks your project needs.

2. Run Checkstyle

Choose one of the following methods. You only need to complete one.

Choose how you want to run Checkstyle

Maven

Choose this if your project uses a pom.xml.

Gradle

Choose this if your project uses build.gradle or build.gradle.kts.

Command Line

Choose this if you want to try Checkstyle without changing your build.

Using Ant? See the Checkstyle Ant Task documentation.

Maven

Add the Maven Checkstyle Plugin to the <plugins> section of your pom.xml: 

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-checkstyle-plugin</artifactId>
  <version>3.6.0</version>

  <configuration>
    <configLocation>config/checkstyle/checkstyle.xml</configLocation>
  </configuration>

  <dependencies>
    <dependency>
      <groupId>com.puppycrawl.tools</groupId>
      <artifactId>checkstyle</artifactId>
      <version>13.11.0</version>
    </dependency>
  </dependencies>
</plugin>

Run:

./mvnw checkstyle:check

If your project does not use the Maven Wrapper, use mvn checkstyle:check.

The Maven plugin has its own release cycle, so the Checkstyle dependency above is specified explicitly to use the version documented on this site.

Once the setup works, you can configure Checkstyle to run automatically as part of your Maven build. See Maven integration for the available options.

Next: Read the result →

Gradle

Apply Gradle's Checkstyle plugin and select the Checkstyle version to use.

For build.gradle:

plugins {
  id 'checkstyle'
}

checkstyle {
  toolVersion = '13.11.0'
}

For build.gradle.kts:

plugins {
  checkstyle
}

checkstyle {
  toolVersion = "13.11.0"
}

Gradle uses config/checkstyle/checkstyle.xml as the default Checkstyle configuration, so the starter configuration created above is already in the expected location.

Run Checkstyle against your main Java sources:

./gradlew checkstyleMain

If your project does not use the Gradle Wrapper, use gradle checkstyleMain.

The Gradle check task also includes the Checkstyle tasks, so Checkstyle can become part of your normal project verification once you are ready.

Next: Read the result →

Command line

The command line is the quickest way to try Checkstyle without modifying a Maven or Gradle build.

Download checkstyle-13.11.0-all.jar from the latest release, then run: 

java -jar checkstyle-13.11.0-all.jar \
  -c config/checkstyle/checkstyle.xml \
  src/main/java

Checkstyle accepts individual Java files or directories. When a directory is supplied, the files inside it are checked recursively.

For all command-line options, see Command Line.

Next: Read the result →

3. Read the result

If Checkstyle finds a wildcard import, you will see a diagnostic similar to: 

Starting audit...
[ERROR] Main.java:1:18: Using the '.*' form of import should be avoided. [AvoidStarImport]
Audit done.
Checkstyle ends with 1 errors.

A Checkstyle diagnostic tells you:

  • the file where the violation occurred;
  • the line and column;
  • what rule was violated;
  • and the Checkstyle check that reported it.

Here, [AvoidStarImport] tells you that the violation came from the AvoidStarImport check. Follow the check name to its documentation to learn what it checks and how it can be configured.

If Checkstyle reports no violations, that is also a successful run — your code simply passes the configured rule.

To verify the setup manually, temporarily add a wildcard import such as: 

import java.util.*;

Run Checkstyle again and confirm that AvoidStarImport is reported.

4. Choose the rules for your project

Now that Checkstyle is running, replace the starter configuration with the coding standard you actually want to enforce.

You can start from one of Checkstyle's supplied configurations:

Google Java Style

Start with Checkstyle's Google Java Style configuration.

Sun Conventions

Start with Checkstyle's Sun Conventions configuration.

OpenJDK Style

Start with Checkstyle's OpenJDK Style configuration.

Doc Style

Start with Checkstyle's Doc Style configuration.

Or create your own configuration by choosing only the checks that make sense for your project.

Browse all checks →
Learn how configuration works →

Where to go next

You're ready. Checkstyle is now set up for your project. Explore the resources below when you want to customize rules, integrations, or advanced behavior.

  • Browse Checks to see the rules Checkstyle provides.
  • Configuration explains how to enable checks and change their properties.
  • Suppressions and Filters let you handle intentional exceptions.
  • Running Checkstyle documents command-line and Ant execution in detail.
  • IDE integrations can provide faster feedback while you write code. See Active Tools.
  • Maven and Gradle integrations can make Checkstyle part of your regular build and CI process.

For most projects, keep the Checkstyle configuration in version control so developers and automated builds use the same rules.