Haskell World logo Haskell WorldWrite code, build worlds
Developer Tools

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.

A developer's laptop on a desk showing a code editor with yellow lint suggestions underlined in Haskell source code

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:

  1. 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.
  2. 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.
  3. 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 runsFeedback timeBest for
Editor through HLSUnder 1 secondCatching hints while you type
Pre-commit hook2 to 10 secondsBlocking obvious issues locally
CI step20 to 40 secondsEnforcing 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.

SR
Sonja Reiter

Sonja Reiter contributed to three major open source projects and started writing documentation when she noticed most tooling guides were written by people who had never taught anyone to use them. She covers build tools, package ecosystems, and the invisible quality-of-life differences between development setups.

More posts by Sonja

More in Developer Tools

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten qvantor rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr webtech1223411 wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto