Haskell HLint Setup and the Hints Worth Ignoring
Your pull request is green, the tests pass, and then a reviewer leaves fourteen comments about redundant brackets and a lambda that could have been a section.

Your pull request is green, the tests pass, and then a reviewer leaves fourteen comments about redundant brackets and a lambda that could have been a section. That review cost both of you half an hour, and a Haskell HLint setup would have caught every one of those notes before you pushed.
HLint is the standard linter for Haskell. It reads your source, matches it against a few hundred rewrite rules, and suggests simpler or more idiomatic code. This guide covers installing it, wiring it into your editor and CI, writing a project config, and deciding which hints deserve to be switched off. I maintain a couple of small libraries and have run HLint on every one of them for years, so the advice below comes from living with its output, not from reading the README once.
Installing Haskell HLint without fighting your toolchain
The quickest route depends on how you already manage GHC. If you use GHCup and cabal, run cabal install hlint and make sure your cabal bin directory, usually ~/.cabal/bin or ~/.local/bin, is on your PATH. With Stack, stack install hlint does the same job. Both builds take somewhere between 4 and 12 minutes on a typical laptop because HLint pulls in ghc-lib-parser, which is large.
One detail trips people up. HLint bundles its own copy of the GHC parser, and each HLint release targets a specific GHC version range. If your project uses syntax newer than the parser HLint was built against, you get parse errors on perfectly valid code. The fix is to upgrade HLint, not to rewrite your code. As a rule of thumb, an HLint release from the last six months handles any GHC from the last two major versions.
If you followed our guide to setting up a Haskell development environment, you already have GHCup and can add HLint in one command.
Running HLint on a real project
From the project root, run hlint . and it walks every .hs file below the current directory. On a 20,000 line codebase that has never been linted, expect somewhere between 150 and 400 hints. Do not try to fix them all in one sitting.
Instead, get a summary first. Adding the report flag to the same command writes an HTML file, report.html, that groups hints by type and counts them. You will usually see that three or four hint types make up most of the noise. On one of my libraries, "Redundant bracket" and "Use fmap" together accounted for 61 percent of all hints.
Applying fixes automatically
HLint can apply many of its own suggestions through the apply-refact tool. Install it with cabal install apply-refact, then run HLint on a single file with the refactor flag and the in-place refactor option, which rewrites the module on disk. Work one module at a time and commit after each, so a bad rewrite is easy to revert. In my experience about 90 percent of automatic fixes are correct, and the remaining 10 percent are mostly whitespace or comment placement you would want to tidy anyway.
Writing a .hlint.yaml that fits your team
Run HLint with its default flag and redirect its output into a file named .hlint.yaml to generate a starter config with every current hint already listed as ignored for your existing code. That gives you a clean baseline: new code is checked, old code is left alone until you choose to clean it.
The config supports four useful entries:
- ignore turns off a hint, either everywhere or within named modules.
- warn and error raise or lower the severity of a hint so CI can fail on the ones you care about most.
- hint adds a custom rewrite rule, for example replacing a deprecated internal helper with its newer version.
- arguments passes extensions such as -XOverloadedStrings so HLint parses your code the way GHC does.
Custom hints are the most underused feature. If your team decided last quarter to stop using fromJust in production code, a three line rule in .hlint.yaml enforces that decision forever, with no reviewer needing to remember it. The same trick works for nudging people from String to Text, which pairs well with our walkthrough on switching your code from String to Text.
The hints worth ignoring, and why the usual advice is wrong
A lot of style guides tell you to treat every HLint suggestion as a rule and drive the count to zero. I think that is bad advice for most teams, and the reason is that some hints trade clarity for brevity in a way that hurts readers.
Three examples I switch off on most projects:
- Eta reduce. Turning f x = g (h x) into f = g . h is shorter, but when the argument has a meaningful name it documents what the function takes. Point free style past two compositions becomes a puzzle for the next person.
- Use concatMap or Use mapM_. These are fine in isolation, yet in code that newer contributors read, an explicit mapM_ over a list comprehension can be clearer than the suggested combinator chain.
- Avoid lambda using an operator section. Sections like (`elem` xs) confuse people who are still learning the language. A plain lambda costs four characters.
The goal is fewer review comments and fewer bugs, not a perfect score. If a hint makes code harder to read for the people who maintain it, disabling it is the correct engineering decision. Write the reason as a YAML comment next to the ignore line so nobody re-enables it blindly.
Editor and CI integration
Haskell Language Server runs HLint as a plugin and shows hints inline, with code actions to apply them. If the hints do not appear, the usual cause is that HLS was built without the hlint plugin or is reading a different .hlint.yaml than you expect. Our Haskell Language Server troubleshooting guide covers how to check which plugins are active.
For CI, add a step that runs hlint src test app after the build. HLint exits with code 1 if it finds any hint at warning level or above, which fails the job. A lint step typically adds 20 to 40 seconds to a pipeline when the binary is cached, so cache it. Pin the HLint version in CI too. A new release can add hints, and you do not want a Tuesday morning build to fail because the linter changed while your code did not.
| Where it runs | Feedback time | Best for |
|---|---|---|
| Editor through HLS | Under 1 second | Catching hints while you type |
| Pre-commit hook | 2 to 10 seconds | Blocking obvious issues locally |
| CI step | 20 to 40 seconds | Enforcing the team baseline |
Frequently asked questions
Is HLint the same as GHC warnings?
No. GHC warnings, enabled with flags like -Wall, catch things the compiler can prove, such as unused imports or incomplete pattern matches. HLint focuses on style and simplification, suggesting shorter or more idiomatic forms of code that already compiles. Most projects run both.
Why does HLint fail to parse my valid Haskell code?
Usually because the HLint binary was built with an older parser than your GHC, or because a language extension is not passed to it. Upgrade HLint first, then add any extensions your cabal file enables to the arguments section of .hlint.yaml. That resolves almost every parse failure.
Should I fix every HLint suggestion before merging?
Not necessarily. Fix the hints that make code clearer or remove real redundancy, and ignore the ones your team finds less readable. Record those decisions in .hlint.yaml so the rules stay consistent and reviewers can stop arguing about style in comments.
More in Developer Tools
Developer Tools
Set Up a Local Hoogle to Search Your Own Dependencies
A student in my second year group spent most of an evening looking for a function that turns a Data.Text value into a lazy...
Developer Tools
Nix Flakes for a Haskell Dev Setup That Stays Put
A student wrote to me at eleven at night in week three of the semester because cabal build failed on a project that had...
Developer Tools
Haskell ghcid Setup for Instant Feedback on Every Save
You save a file, switch to a terminal, type the build command, wait twenty seconds, and read a wall of errors that scrolled...