Gentoo distfiles can grow quietly because Portage keeps source archives after packages finish building. Cleaning them frees disk space without unmerging installed packages, but an overly aggressive pass can force later rebuilds to download sources again or lose convenient downgrade archives.
The eclean-dist utility compares cached source archives with the ebuild repositories. Its default mode protects archives referenced by available ebuilds, including versions that are not installed, so the cache can still support downgrades and reinstallations.
A source cache is especially valuable on systems with limited network access or manually downloaded software. Archives that cannot be downloaded again need a separate backup before cleanup, and sources for installed packages whose ebuilds have disappeared may need protection even in the default mode.
Steps to clean Gentoo distfiles:
- Install gentoolkit if eclean-dist is missing.
# emerge --ask app-portage/gentoolkit
The app-portage/gentoolkit package supplies eclean-dist. Commands shown with a # prompt run from a root shell on the Gentoo system; an account with sudo access can prefix them with sudo.
- Find Portage's active distfiles directory.
# portageq envvar DISTDIR /var/cache/distfiles
DISTDIR defaults to /var/cache/distfiles and may be overridden in /etc/portage/make.conf. If the printed path differs, that path replaces /var/cache/distfiles in the size check.
- Check the space used by the source cache before cleanup.
# du -sh /var/cache/distfiles 6.2M /var/cache/distfiles
- Preview the obsolete archives selected for removal.
# eclean-dist --pretend >>> Building file list for distfiles cleaning... >>> Here are the distfiles that would be deleted: [ 3.0 M ] gentoolkit-0.8.0.tar.bz2 =========== [ 3.0 M ] Total space from 1 files would be freed in the distfiles directory
–pretend leaves the files untouched. Filenames and sizes depend on the cache; an already-clean message means there is nothing to remove. The default mode keeps more sources than –deep, which protects only installed versions and can discard archives needed for downgrades or reinstalling removed packages.
If the preview lists an archive needed for offline rebuilding or reports unavailable installed packages, postpone deletion until those sources have a backup outside DISTDIR. Sources for unavailable ebuilds may not be protected automatically.
- Remove the obsolete archives with the default cleanup mode.
This permanently deletes the selected cached archives. Installed packages remain installed, but a later rebuild may need to download the removed sources again.
# eclean-dist >>> Building file list for distfiles cleaning... >>> Cleaning distfiles... [ 3.0 M ] gentoolkit-0.8.0.tar.bz2 =========== [ 3.0 M ] Total space from 1 files were freed in the distfiles directory
- Confirm that no obsolete distfiles remain.
# eclean-dist --pretend * Building file list for distfiles cleaning... * Your distfiles directory was already clean.
The already-clean message confirms there are no more candidates under the same cleanup policy. Archives still protected by available ebuilds remain in the cache, so the directory need not be empty.