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 ByteString .

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 ByteString. She searched the public Hoogle, found something with the right shape, added the import, and got a compile error, because the package that exported it was not among her dependencies and the version she did have had moved the function elsewhere. The thing she needed was already installed on her laptop. It was one import away the whole time.
That gap is the reason I now set up a local Hoogle database in any project with more than a handful of dependencies. The public instance indexes a curated snapshot of packages. Your project indexes exactly what you can import today, including the internal modules of your own library, which is the set you actually care about when you are stuck mid function. Setting it up takes under ten minutes the first time and a single command after that, and the step most tutorials put first is the one I would skip.
What a local database knows that the website does not
Three differences matter in daily work, and only the first one is obvious.
The local database contains your own code. If you have written a module with forty helper functions over a semester, Hoogle will find them by type signature alongside everything from base. I use this constantly on my own teaching material, where I can never remember whether the helper I wrote in March took a list or a vector. Searching by shape beats grepping for names you half remember.
It also contains the exact versions you resolved. The public instance answers for one snapshot. If your build plan pinned aeson at an older major version, the website will cheerfully show you a function that does not exist for you yet. That is the failure my student hit, and it is the kind of error that teaches beginners to distrust the tooling instead of the version number.
Finally, it works without a network. The reason I care is not air travel, it is latency. A local query returns in something like 20 to 60 milliseconds, which is fast enough that you search in the middle of writing a line rather than deciding it is not worth the interruption. That change in habit is the real payoff, and it is hard to appreciate until you have it.
The setup, in the order I run it
This is the cabal path. Stack users have a shortcut and I cover it below.
- Install the tool itself with cabal install hoogle. It takes four to eight minutes to build on a laptop and lands a binary in your cabal bin directory. Check it is on your PATH before continuing, because a missing binary later looks like a database problem.
- Generate Haddock output in Hoogle's text format for your project and every dependency. That is cabal haddock with the hoogle flag set and the option that asks it to cover all packages in the plan, not just the local one. Expect three to twelve minutes for a project with a hundred or so transitive dependencies, and expect it to be the slowest step by a wide margin.
- Build the database from those text files, pointing the generate command at the directory holding them with the local option. On a plan of around 120 packages this takes 40 to 90 seconds and produces a single file of roughly 150 to 300 MB.
- Add that file to your ignore list. It is binary, it is big, and it is reproducible from step two. I have reviewed a pull request that contained a 280 MB database. Once was enough.
- Query it. For one off lookups, the command line search is quicker than a browser: pass the database path and the query, and you get ten results in a terminal. For browsing, start the server on a port you remember and leave it running in a background tab.
Stack compresses this into one command, stack hoogle, which builds the tool, generates the Haddock text, and assembles the database in one pass, then forwards further arguments to the underlying tool so you can run a search or a server through it. It is genuinely easier. The cost is less visibility when a step fails, and failures here are quiet.
Wire the regeneration into whatever you already type. Mine is a Makefile target next to the one that runs tests, and I run it after any change to the dependency list. If you work inside a GHCi session all day, which is the pattern I argue for in the note on using GHCi as your daily workflow, the natural moment to regenerate is right after the reload that follows a cabal file edit.
Searching by shape, which is the part people skip
Most people use Hoogle as a name lookup, type in a function they half recall, and find it. That works and it wastes the tool. The signature search is what makes the local copy worth the disk space.
Write the shape of the hole you are staring at. Searching for a function from a list of results to a result of a list finds the traversal you want without knowing it is called sequence. Searching for a transformation over a container finds fmap, traverse, and about nine variants you did not know existed in packages you already depend on. Type variables are fine, concrete types narrow it sharply, and a leading double colon restricts the match to signatures rather than names.
The habit worth teaching: when you know what you have and what you want, write both, separated by an arrow, and search that before you search anything else. In the class I teach, students who learn this in week three stop asking me which function converts between two string types, because the answer takes them eight seconds to find and they trust it, since it came from their own build plan.
Why I skip the step every tutorial starts with
Nearly every guide opens by telling you to run the generate command with no arguments, which downloads and indexes a full package snapshot, something in the region of 2,800 packages. It takes 15 to 40 minutes, consumes well over a gigabyte, and gives you the complete ecosystem offline. I think it is the wrong first move, and I have stopped recommending it.
The reason is that the full snapshot recreates the exact problem the local database was supposed to solve. You get results from packages that are not in your build plan, so every promising answer needs a second check against your dependency list. For a beginner that check is invisible, and the result is another evening like my student's. A project scoped database cannot lie to you that way: if it is in there, you can import it.
There is one case where the full snapshot earns its place, and it is library shopping. When the question is whether anything on Hackage already solves a problem, you want breadth, and breadth is what the website is for anyway. I keep a full database on one machine and project databases everywhere else. If you only build one, build the project one.
Two sharp edges are worth knowing before you hit them. A dependency whose Haddock build fails leaves no entries in the database and says nothing about it, so a search that returns nothing for a package you know you depend on usually means a broken documentation build, not a broken query. And upgrading the tool invalidates the database format, which surfaces as a version mismatch error that reads like file corruption. Regenerating fixes it. If you are also writing documentation for others, the notes on Haddock documentation people actually use explain why the signatures and comments you write end up being what Hoogle indexes.
FAQ
Does Haskell Language Server make this redundant?
No, they answer different questions. The language server tells you about identifiers in scope and the types at a cursor position. Hoogle answers what function with roughly this shape exists anywhere in my dependencies, which is a search across code you have not imported yet. I keep both and reach for them at different moments.
How often do I need to regenerate the database?
After any dependency change, and after you add modules you want searchable. Day to day editing of existing function bodies does not need it. A regeneration on an already built project takes about a minute, since the slow Haddock pass only reruns for what changed.
Can I search my private company packages?
Yes, and this is the strongest argument for the local setup in a work context. Anything in your build plan gets indexed, including internal packages from a private repository, which no public instance can ever see. Nothing leaves the machine either.
Is it worth it for a small project?
For a single file script with three imports, no. Use the website. The break even point in my experience is somewhere around fifteen dependencies or the moment you have written enough of your own helpers to forget their names. Other tooling choices with similar break even points are collected in the dev tools section.
More in Developer Tools
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...
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...