How to Deprecate a Haskell Package Without Breaking Users
I retired a small Haskell package in 2023 and did it in exactly the wrong order. It was a tokenizer I had written for a class exercise, about 400 lines, with roughly 40 reverse dependencies on Hackage by the time I stopped caring about it.

I retired a small Haskell package in 2023 and did it in exactly the wrong order. It was a tokenizer I had written for a class exercise, about 400 lines, with roughly 40 reverse dependencies on Hackage by the time I stopped caring about it. I set the deprecated flag on the package page, added a line to the README pointing at a better library, and considered the job finished. Two weeks later a graduate student emailed me because her continuous integration pipeline had started failing on a package she had never heard of, and the only clue she had was my package name sitting three levels deep in a build plan.
Nothing I did was technically wrong. The trouble was that none of it reached the people who needed it. Retiring a library is mostly a communication job with a small amount of metadata attached, and most maintainers do the metadata first and the communication never. Done properly it takes one afternoon and saves you a long tail of confused reports that all say the same thing.
What the deprecated flag on Hackage actually does
Less than almost everyone assumes. Marking a package deprecated through the Hackage web interface does two things: it hides the package from search results, and it prints a short notice on the package page. It does not block installs, does not warn during a build, and does not surface anywhere in cabal output. Anyone who has your package pinned in a freeze file, which describes most production projects, will never see that flag at all.
The warning real users encounter comes from GHC, and you have to put it in the source yourself. A module level pragma such as {-# DEPRECATED "Unmaintained since March 2024. Use the text based tokenizer instead." #-} placed under the module header makes every import site produce a warning on the next compile. In my experience that is the only mechanism that reaches somebody who is not reading your repository. The compiler walks into their terminal uninvited; your README waits to be visited.
There is a second pragma worth knowing. You can deprecate individual exports rather than whole modules, which matters if you are retiring half a library instead of all of it. Marking three functions and leaving the rest alone gives users a path instead of a wall, and it keeps the download count honest for the parts people still want.
The order I use now
This is the sequence I follow, and the order carries most of the value. Each step assumes the one before it is already done.
- Write down what users should do instead, in one sentence. If you cannot name a replacement, write the honest version: there is no successor, copy the 30 lines you need into your own project. A retirement notice without a destination generates more mail than it prevents.
- Cut a final release that adds nothing but warnings. Patch bump only, 0.6.1 to 0.6.2. Add the pragmas, add a changelog entry, change no signatures. Mixing an API change into the farewell release is how you turn a warning into a build failure.
- Write the changelog entry for someone in a hurry. First line names the replacement. Second line gives the date you stop testing against new GHC releases. Nobody reads paragraph two of a changelog, so do not hide the useful part there.
- Edit the synopsis field in the cabal file. The first 60 characters of that string show up in search results and in
cabal infooutput. Prefixing it with "DEPRECATED:" puts the status in the one place tooling reliably reproduces. - Set the Hackage flag last, and fill in the replacement field. It accepts a list of package names, and those names become links on the page. An empty replacement list is a dead end for whoever lands there from a search engine six months later.
- Open a tracking issue titled "This package is deprecated" and pin it. Leave it open. Closed issues do not get read, and the pinned issue is the first thing a visitor sees on the repository tab where they are already looking for an answer.
- Answer the last wave of reports with a link for about six months, then stop. My own tail ran four months and eleven messages. After that the traffic was search engine noise, not users.
Steps two through five fit in ninety minutes if the code is already in front of you. The first step is the one people skip, and it is the only one that requires thinking.
The advice I stopped following
The common recommendation is to make the deprecation loud with a major version bump, 0.6 to 1.0 or 1.4 to 2.0, on the theory that a big number gets attention. I tried that once and it caused more disruption than the retirement itself.
A major bump tells every piece of tooling in the ecosystem that you have shipped a new feature line. Bots open pull requests to relax upper bounds so projects can move to it. Curators consider it for the next snapshot. Worst of all, every user whose bounds read < 1.0 receives nothing, and that conservative group is precisely the one you were trying to warn. Warnings travel on patch releases, because patch releases get installed by people who never decided to install anything. Leave the major number alone and let the compiler carry the message. If you want the reasoning behind what each digit promises, our notes on Haskell PVP versioning for maintainers cover the contract in detail.
One related mistake is genuinely irreversible: do not delete the repository. The package stays on Hackage forever, the source link goes dead, and anybody who wants to vendor the 30 lines they depend on now has to extract them from a tarball. Archiving a repository costs nothing and keeps the issue history readable.
What the replacement note should actually say
Three facts, in this order. What to use instead. What breaks if they switch. What they lose if they do nothing.
The third one is the part maintainers leave out, and it is the only part that lets a reader make a decision. A note that reads "the replacement library covers the same cases, the function names match except that the pretty printer takes a configuration record as its first argument now, and if you stay here the package keeps compiling on GHC 9.4 and 9.6 but will not be tested past that" answers the question somebody is about to ask you. A note that reads "this package is no longer maintained, please migrate" does not.
Keep the whole thing under 80 words. It has to fit in a pragma string, a changelog line, and a pinned issue without being rewritten three times, and shorter text survives copying better.
When a package should not be retired at all
A finished library is not a dead one. If your package does one narrow job, compiles clean on the current compiler, and has no open issues, the correct action is nothing. I watched a small vector arithmetic package get deprecated by an author who felt guilty about not having touched it in two years, which prompted four projects to migrate to something larger and slower for no reason. The code had not stopped working. Only the author's confidence had.
The better move in that case is a line in the README stating that the package is complete and that you will respond to build failures but not feature requests. If even that feels like too much, hand the package to somebody else before flagging it. Our walkthrough on taking over an abandoned Haskell package is written from the receiving end, and it describes what a new maintainer needs from you: the Hackage maintainer group, the repository, and an hour of your attention.
If you do have the afternoon, start with step one and nothing else. Open a text file and write the single sentence telling your users where to go. If you cannot finish that sentence, the package is not ready to retire, and you have learned the most useful thing available this week.
FAQ
Can I remove a package from Hackage entirely?
Not on your own, and not quickly. Hackage treats uploads as permanent so that old build plans keep resolving. Administrators will remove a release in narrow cases, such as an accidental upload containing credentials, but a change of heart is not one of them. Plan on the package existing forever.
Will the deprecation pragma break builds that use strict warning flags?
Yes, for anyone compiling with warnings promoted to errors, which is common in library projects. That is a real cost and the reason the warning release has to be a patch bump with no other changes: a user who hits it can pin the previous patch version in one line and deal with the migration on their own schedule.
How long should the final version keep working?
Pick a compiler, not a date. Saying the package is tested on GHC 9.4 and 9.6 and will not be updated past that gives users a concrete horizon they can plan around, usually about two years in practice. Dates get ignored; a compiler version appears in their own build output.
Should I file issues against projects that depend on my package?
Only for the handful with recent activity, and only once each. I opened six, got three replies, and two of those maintainers had already seen the compiler warning. Opening forty issues across dormant repositories reads as noise and does not move anybody.
More in Open Source
Open Source
How to Review a Pull Request on a Haskell Project
A contributor sent a 38 line patch to a logging package I help maintain.
Open Source
How to Vet a Haskell Dependency Before You Add It
A student in my second year class added a JSON library to her project because it was the first result she found and the README...
Open Source
How to Write a Haskell Bug Report Maintainers Can Fix
You hit a crash in a Haskell library, open the issue tracker, and type three lines about what broke.