# CheckStyle-IDEA: running Checkstyle as an IntelliJ inspection

> CheckStyle-IDEA is a JetBrains plug-in that checks your code against a CheckStyle 10 to 14 profile while you type, with configurable scan scopes, a commit-time check that can abort a commit, Eclipse-CS variable support for multi-module builds and an explicit opt-in for external DTD loading. It is the fast way to see style problems in the editor rather than in a build log.

**jshiell/checkstyle-idea** — CheckStyle plug-in for IntelliJ IDEA

- Repository: https://github.com/jshiell/checkstyle-idea
- Website: https://plugins.jetbrains.com/plugin/1065-checkstyle-idea
- Stars: 918 · Forks: 155
- Language: Java
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/jshiell-checkstyle-idea

## An inspection, not a build task

CheckStyle-IDEA is a plug-in for JetBrains IntelliJ IDEA 2025 and 2026 that provides real-time feedback against a given CheckStyle 10 to 14 profile by way of an inspection. That single sentence defines the product. It is not a formatter, it is not a rewrite tool, and it does not run on a schedule.

The plugin surface is small and familiar if you have used any IntelliJ inspection. Once installed, a new inspection appears in the group named CheckStyle, and you turn it on and configure it from the Inspections item in the preferences panel.

The rest of the configuration lives in the Settings dialogue under Tools and then Checkstyle, and that one place controls both the inspection and the static scanning, which is a sensible consolidation: the profile you see in the editor is the profile the scanner uses.

Two facts about the project are worth knowing before you install it. It is not an official part of Checkstyle, and the project says so plainly, noting that Checkstyle neither endorses nor bears responsibility for it. And the logo comes from the Checkstyle resources repository and is used under the CC BY 4.0 licence, while the plug-in itself is released under a BSD-style licence with the details in the LICENCE file. The distribution channel is the JetBrains plugin marketplace, at plugins.jetbrains.com, which is where an IntelliJ user will look for it.

## The scan scope decides which files Checkstyle ever reads

A Checkstyle run over a whole project is slow, so the scan scope dropdown is the setting that makes the plug-in usable. It offers five options, and the documentation is precise about each one.

Only Java sources, but not tests, means Java files under source roots, excluding test source roots, and that is the default. Only Java sources, including tests, scans the test source roots as well. All sources, but not tests, covers every file under the source roots whatever its type, still excluding tests. All sources, including tests, does the same including test roots. All files in project goes further still and reads every file in the project regardless of whether it sits under a source root.

The progression is from narrow and fast to wide and slow, and the two axes are file type and test inclusion. For a large project where only Java matters, the default is the right one, and the difference between it and All files in project is the difference between a responsive editor and a stalled one.

Worth noting that the scope applies to the static scanning. The inspection itself reports on the file you are editing, so the practical limit on the editor side is different from the one on the scan side, and users often find that the two settings behave differently until they realise why.

## The commit check can abort a commit from the changelist

The Scan modified files before commit checkbox runs Checkstyle over the files in the changelist when you commit, and offers to abort the commit if any problems are found.

What makes this worth understanding is that the same option appears in three places: in the plugin settings, in the commit dialogue itself, and under Settings, then Version Control, then Commit. The documentation points out that all three edit the same setting, so configuring it in one place changes it in the others. That is good news for anyone who has wondered why the commit dialog keeps offering to check their changes without them having enabled anything there.

The scope of the check is the changelist, not the whole project, which is what makes it fast enough to run on every commit. In a team, this is the part that changes behaviour: a style violation gets caught before it becomes a diff comment, and the commit can be stopped at the point where it costs nothing.

What it does not do is enforce anything on a server. An editor-side check only helps the people running that editor, so if the project runs Checkstyle in the build, the build remains the place where the rule is actually enforced.

## Detecting a configuration file is manual and deliberately conservative

The Detect Checkstyle Configuration File action, in the CheckStyle tool window action group, scans the project root for a Checkstyle configuration file at one of three conventional locations, in priority order.

```bash
config/checkstyle/checkstyle.xml
checkstyle.xml
etc/checkstyle.xml
```

The first of those is the Gradle and Maven Checkstyle plugin default, which is why it is first. The first match wins, and there is no merging of multiple matches, so a repository with two configuration files does not get a blended profile.

The behaviour around that action is where the design shows care. It is a manual action and does not watch the filesystem, so you invoke it again after a location appears or disappears, for instance after a git pull. Each invocation is idempotent: it adds a location for the first match found, removes it again if nothing matches any more, and otherwise leaves things as they are.

And it only ever manages the single location it created itself, so it never overrides or removes a location you added by hand under a different description or path. The documentation notes the rare edge case where a hand added location with exactly the same description, path and type as the detected one may be adopted as the managed location. That level of detail about an edge case tells you how much the action is used in practice.

## Eclipse-CS variables are what make one rules file work across modules

If your build has several modules, a single Checkstyle rules file usually needs to point at a different suppression file in each one. The plug-in supports the Eclipse-CS variable conventions for that.

Five variables are available unless you override them. basedir maps to the external project directory of the current module, the Gradle subproject or Maven module directory, and falls back to the module content root and then to the project directory. project_loc and workspace_loc both map to the project directory. config_loc and samedir map to the directory the rules file is in, or to the project directory for remote rules files such as ones fetched over HTTP.

The values you set under the Edit Properties button may also reference these variables, and that is the mechanism for giving a single property a different value in each module. The example in the documentation sets a baseDir property to the basedir variable and references it from the rules file.

```xml
<module name="SuppressionFilter">
    <property name="file" value="${baseDir}/gradle/checkstyle-exclude.xml"/>
    <property name="optional" value="true"/>
</module>
```

That resolves each subproject's own suppressions file. A reference to a variable that is not set is left as it is, which means an unresolved reference shows up in the output as a literal rather than as an empty path, and that is a useful failure mode to recognise.

## External DTD loading is an opt-in with a real security cost

A rules file can pull in other files with XML entity includes, with paths resolved relative to the including file.

```xml
<!DOCTYPE module PUBLIC "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
        "https://checkstyle.org/dtds/configuration_1_3.dtd" [
        <!ENTITY additionalModules SYSTEM "./additional-modules.xml">
        ]>
<module name="Checker">
    <module name="TreeWalker">&additionalModules;</module>
</module>
```

Checkstyle does not resolve these unless you opt in, and neither does the plug-in. To enable them you add the following through Help and then Edit Custom VM Options, and restart the IDE.

```bash
-Dcheckstyle.enableExternalDtdLoad=true
```

The same opt-in is what the Checkstyle CLI and the Gradle plugin require. The plugin documentation then spells out the consequences in unusually blunt terms. It is an IDE-wide setting rather than a per-project one, and it enables external entity resolution generally, including entities with absolute http URLs, which are fetched without any plugin-side resolver in front of them. The advice is to enable it only if you trust the rules files you open.

Two smaller rules come with it. Includes are resolved relative to rules files on the local filesystem, so a rules file loaded over HTTP or from the third-party checks classpath has nothing to resolve a relative include against and its includes will not be found. And the Third Party Checks tab, which lets you add directories or JAR files to the Checkstyle classpath, loads those checks only in trusted projects, because the entries are read from the project's own .idea/checkstyle-idea.xml and loading a check means running its code.

## Release numbers that track the IDE, and a build on Gradle

The version scheme is the first thing to notice when you look at the releases. The recent tags are 26.19.1 from 2026-10-07, 26.19.0 from 2026-10-03 and 26.18.2 from 2026-09-12, and the numbers line up with the IntelliJ release cycle that the plug-in targets, 2025 and 2026 builds. A user therefore ends up on a plug-in version whose number tells them which IDE generation it was built for.

The last push was on 2026-10-19, the repository is not archived, and the default branch is main. The project keeps a CHANGELOG.md at the root and an AGENTS.md alongside it, which in practice means contributors are expected to work with coding assistants on a Java codebase.

The build itself is Gradle, with build.gradle.kts, buildSrc, settings.gradle.kts and the wrapper scripts for Unix and Windows, plus a mise.toml for tool version management. Building the plug-in from source therefore means the same toolchain most IntelliJ plugin projects use.

For licence terms, the licence field on the repository carries a custom classification that GitHub cannot label, and the authoritative text is the LICENCE file, which the project describes as a BSD-style licence. The logo is a separate matter, used under CC BY 4.0 from the Checkstyle resources repository.

## Conclusion

Adopt CheckStyle-IDEA when your team already standardises on CheckStyle and wants violations to appear in the editor instead of only in a build log, especially in a multi-module build where per-module suppression files matter. Do not adopt it as your enforcement point, because a plug-in cannot gate a commit on a server, and treat the external DTD option as a security decision rather than a convenience, since it is an IDE-wide switch that resolves http entities without a plugin-side resolver. Before enabling the inspection, check that the CheckStyle version bundled with the plugin supports the profile you intend to use, run the Detect Checkstyle Configuration File action once so the project root points at your real config, and confirm that your build continues to run Checkstyle from Gradle or Maven rather than relying on the editor to catch everything.

## FAQ

### Is CheckStyle-IDEA an official Checkstyle project?

No. The project states plainly that it is not an official part of Checkstyle, and that Checkstyle neither endorses nor bears responsibility for the plugin. The logo comes from the Checkstyle resources repository and is used under the CC BY 4.0 licence.

### How do I turn on Checkstyle checking in IntelliJ IDEA?

Once the plugin is installed a new inspection appears in the group named CheckStyle, and you enable and configure it from the Inspections item in the preferences panel. The profile and scan scope are configured under Settings, then Tools, then Checkstyle, which controls both the inspection and static scanning.

### Can the plugin block a commit when Checkstyle finds problems?

Yes. The Scan modified files before commit option runs Checkstyle over the files in the changelist at commit time and offers to abort the commit if problems are found. The same setting is exposed in the plugin settings, in the commit dialogue, and under Settings, then Version Control, then Commit.

### How do I share one Checkstyle rules file across Gradle or Maven modules?

Use the Eclipse-CS variables the plugin provides, including basedir, project_loc, workspace_loc, config_loc and samedir, and set a property to the basedir variable under Edit Properties. Referencing that property from a SuppressionFilter then resolves each subproject's own suppressions file, and an unset variable is left as it is.

### What does the checkstyle.enableExternalDtdLoad option do and is it safe?

It lets a rules file pull in other files through XML entity includes, and the plugin requires the same opt-in as the Checkstyle CLI and the Gradle plugin. It is an IDE-wide setting that enables external entity resolution generally, including absolute http URLs fetched without a plugin-side resolver, so the documentation advises enabling it only for rules files you trust.

## Sources

- [Issues](https://github.com/jshiell/checkstyle-idea/issues)
- [jshiell/checkstyle-idea on GitHub](https://github.com/jshiell/checkstyle-idea)
- [Project website](https://plugins.jetbrains.com/plugin/1065-checkstyle-idea)
- [README](https://github.com/jshiell/checkstyle-idea/blob/main/README.md)
- [Releases](https://github.com/jshiell/checkstyle-idea/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jshiell-checkstyle-idea