LinuxCommandLibrary

eclean

Clean Gentoo's Portage package cache

TLDR

Clean the source file directory

$ sudo eclean distfiles
copy

Clean the binary package directory
$ sudo eclean packages
copy

Clean the distfiles of all uninstalled packages, but keep the distfiles of installed packages
$ sudo eclean [[-d|--deep]] [[-n|--package-names]] distfiles
copy

Clean the binary packages of all uninstalled packages, but keep the binaries of installed packages
$ sudo eclean [[-d|--deep]] [[-n|--package-names]] packages
copy

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.

SEE ALSO

emerge(1), portage(5), ebuild(5), dispatch-conf(1)

Copied to clipboard