cabal-clean: Remove outdated cabal build artefacts from `dist-newstyle`.

[ bsd3, development, program ] [ Propose Tags ]

Simple command line tool to remove cabal build artefacts from `dist-newstyle/build` that are superseded by newer versions of the built package or the Haskell compiler.

[Skip to Readme]


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Versions [RSS] 0.1.20210815, 0.1.20210924, 0.1.20220814, 0.2.20220819, 0.2.20230609
Change log
Dependencies base (>=4.9 && <5), containers (>=0.5.8), directory, filemanip (>=, filepath, mtl, optparse-applicative (>=0.13), pretty-terminal, process, silently (>=, split, string-qq [details]
License BSD-3-Clause
Copyright Andreas Abel, 2021, 2022
Author Andreas Abel
Maintainer Andreas Abel <>
Category Development
Home page
Bug tracker
Source repo head: git clone
Uploaded by AndreasAbel at 2023-06-09T14:35:35Z
Distributions LTSHaskell:0.2.20230609, NixOS:0.2.20230609, Stackage:0.2.20230609
Executables cabal-clean
Downloads 692 total (24 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
Last success reported on 2023-06-09 [all 1 reports]

Readme for cabal-clean-0.2.20230609

[back to package description]

Hackage version cabal-clean on Stackage Nightly Stackage LTS version Cabal build

cabal-clean : Remove superseded artefacts of cabal v2-build

Removes compilation artefacts in dist-newstyle/build from older versions of the package or superseded minor versions of GHC.

For the impatient


cabal install cabal-clean



This lists the build artifacts under dist-newstyle/build.

---	191M	dist-newstyle/build/x86_64-osx/ghc-7.10.3/$MY_PROJECT-2.9.2
---	 72M	dist-newstyle/build/x86_64-osx/ghc-8.10.4/$MY_PROJECT-2.9.2
---	162M	dist-newstyle/build/x86_64-osx/ghc-9.0.1/$MY_PROJECT-2.9.2
+++	135M	dist-newstyle/build/x86_64-osx/ghc-7.10.3/$MY_PROJECT-2.9.3
---	 70M	dist-newstyle/build/x86_64-osx/ghc-8.10.4/$MY_PROJECT-2.9.3
+++	145M	dist-newstyle/build/x86_64-osx/ghc-8.10.7/$MY_PROJECT-2.9.3
---	159M	dist-newstyle/build/x86_64-osx/ghc-9.0.1/$MY_PROJECT-2.9.3

The superseded ones (assuming ghc-9.0.1 is not on the PATH), printed in red and prefixed by dashes (---), can then be removed by:

cabal-clean --delete


v2-cabal (the nix-based cabal) maintains a directory structure for local builds of the form dist-newstyle/build/$ARCH/$HC/$PACKAGE-$VERSION (plus other stuff that does not take up much disk space). During active development with several $HC versions and $VERSION bumps for the $PACKAGE, lots of out-dated build artefacts accumulate over time.

A simple way to clean up is removing the whole dist-newstyle folder, but one might want to keep the build artefacts of the most recent package $VERSIONs of the most recent versions of the Haskell compiler ($HC).


  • Go for saving the most disk space with the simplest approach, rather than a complete clean-up. E.g., don't care about outdated contents in dist-newstyle/package-db as they take little space.

  • Keep only the most recent $VERSION of the package.

  • Keep only the most recent major versions of $HC.

  • Keep only versions build with a $HC which is still on the PATH (since version 0.2).

  • Assume a monopoly of GHC, ignoring other Haskell compilers, so only treat $HCs of the form ghc-$GHCVER.

  • Work autonomously, ignoring cabal files. This saves us parsing various home-grown cabal file formats. The latter could be easy using the Cabal package, but this package is not very stable, and we shy the maintenance effort of depending on Cabal.

  • Dry-run is the default, giving the user opportunity to review the clean-up plan.


  • Read the contents of dist-newstyle/build, organizing them into a tree according to the pattern $ARCH/ghc-$GHCVER/$PACKAGE-$VERSION.

  • Display the outdated versions.

    Try to get the disk usage with du -h and display it. (I could not find a Haskell library that gets the disk usage OS-agnostically.)

  • With option --delete actually remove the respective folders.


List build artifacts of current project, marking superseded ones that can be deleted:


Actually delete superseded builds:

cabal-clean --delete

Delete superseded builds without changing to directory:

cabal-clean --delete path/to/my/project/dist-newstyle

Delete superseded builds in many projects:

find . -name "dist-newstyle" -exec cabal-clean --delete {} \;

Get help:

cabal-clean --help

cabal v2-clean (as of 2021-08-16)

  • Removes all build artefacts.
  • Does not have a --dry-run preview.