eclean
Clean Gentoo's Portage package cache
TLDR
Clean the source file directory
Clean the binary package directory
Clean the distfiles of all uninstalled packages, but keep the distfiles of installed packages
Clean the binary packages of all uninstalled packages, but keep the binaries of installed packages
SYNOPSIS
eclean subcommand [options]
eclean distfiles [-adfpqstv] [--all] [--deep] [--destructive] [--force] [--pretend] [--quiet] [--size] [--time time] [--verbose]
eclean packages [-dfpqstv] [--destructive] [--force] [--pretend] [--quiet] [--size] [--time time] [--verbose]
PARAMETERS
distfiles
The subcommand to clean up source archives (distfiles) located in $PORTAGE_DISTDIR (usually /var/cache/distfiles).
packages
The subcommand to clean up temporary build directories and binary packages located in $PORTAGE_TMPDIR (usually /var/tmp/portage).
-d, --destructive
Perform the actual removal of files. By default, eclean runs in dry-run mode.
-p, --pretend
Perform a dry-run; show what would be removed without actually deleting files. This is the default behavior.
-s, --size
Display the total size of files that would be removed or have been removed.
-f, --force
Do not prompt for confirmation before removal.
-q, --quiet
Suppress most output messages.
-v, --verbose
Enable verbose output, showing more details about files being processed.
-t time, --time time
Remove files older than the specified time. Examples: 30d (30 days), 1w (1 week), 2m (2 months).
-a, --all (distfiles only)
Remove all distfiles, even those still referenced by Portage. Use with extreme caution, as this can break future installations or updates.
-D, --deep (distfiles only)
Remove distfiles not referenced by any currently installed packages. This is a common and safer way to deep clean distfiles.
DESCRIPTION
eclean is a command-line utility integral to the Gentoo Linux Portage package management system. Its primary function is to reclaim disk space by removing unneeded files accumulated during system operation and package management.
It operates on two main categories:
distfiles: These are the source archives downloaded by Portage to build packages. Over time, multiple versions of source files can accumulate, consuming significant disk space. eclean distfiles helps manage this by removing older or unreferenced source files, retaining only those required by currently installed packages or specified configurations.
packages: These refer to temporary build directories and potentially binary packages created by Portage, typically found under /var/tmp/portage/. While Portage often cleans these up after successful installation, eclean packages ensures that any lingering build artifacts from previous builds, failed installations, or manual interventions are properly cleared.
eclean is a critical tool for maintaining disk hygiene and efficiency on Gentoo systems, especially given Portage's source-based nature, which can generate substantial temporary and archived data.
CAVEATS
1. Dry-run by default: eclean runs in pretend mode by default. Always double-check its output using -p before running with -d (--destructive) to avoid accidental data loss.
2. --all option: The --all option for eclean distfiles is highly dangerous. It removes all source archives, even those currently required, potentially breaking future package installations or updates if Portage cannot re-download them.
3. Gentoo-specific: eclean is a utility specific to Gentoo Linux and its Portage package manager. It will not function on other Linux distributions.
4. Scope: eclean only manages files within Portage-specific directories (distfiles cache, build temporary spaces). It does not clean user home directories, system logs, or other general system clutter.
HISTORY
eclean is an integral part of the Portage package management system, which was developed concurrently with Gentoo Linux itself. Its evolution is directly tied to the needs of a source-based distribution, where large quantities of source archives (distfiles) and temporary build artifacts accumulate rapidly. Introduced to provide a straightforward method for disk space management, eclean has been a standard and essential utility for Gentoo users for many years, reflecting the ongoing commitment to system hygiene within the distribution's design philosophy.