eclean-kernel /

Filename Size Date modified Message
1.3 KB
16 B
4.4 KB
632 B
871 B



eclean-kernel is a small tool aimed at removing old and stale kernel files. It does not only remove old kernels itself but also tries to remove all related files including auxiliary files in /boot, kernel modules and even the source tree.


The typical use is:

eclean-kernel -n 3 -p

where -n 3 is used to keep three newest kernels around, and -p makes eclean-kernel only print kernels which would be removed.

In case the results are satisfactory, use:

eclean-kernel -n 3

to actually remove the kernels.

If you are unsure whether kernel files are mapped correctly, you can use list mode:

eclean-kernel -l

which just lists found kernels with file mappings.

Configuration file

Some default options can be specified in eclean-kernel.rc file in a location mandated by the XDG configuration directory setting, e.g. ~/.config/.

The file format is very simple -- additional command-line options are specified in shell style. For example, to keep three newest kernels and always preserve kernel configs, ~/.config/eclean-kernel.rc would contain:

-n 3 -x config

The options read from config files will be parsed before actual command-line options, so the latter will override them.

Fiding and mapping kernels

The first task performed by eclean-kernel is finding all currently installed kernels and matching auxiliary files to them. In order to do that, eclean-kernel first looks for files named in the form of:


where PREFIX is one of the predefined file prefixes representing the file type, and VERSION is a free-form string following it (preferably the kernel version).

Right now, eclean-kernel supports the following prefixes:

  • vmlinuz, vmlinux, kernel and bzImage for kernel files,
  • for file,
  • config for kernel configuration.

In case support for additional prefixes is needed, feel free to report a bug.

Files belonging to the same kernel are grouped using the VERSION part, e.g. it is assumed that corresponds to vmlinuz-X.Y.Z.

In addition to that, eclean-kernel looks for kernel modules in:


where REALVERSION corresponds to the actual kernel version string used by the kernel itself. It is read from kernel image itself and it is assumed to be equal to VERSION for libdirs unmatched to any kernel image.

In other words, genkernel-generated kernel-genkernel-ARCH-X.Y.Z will be matched to but also to /lib/modules/X.Y.Z.

Choosing kernels to remove

The kernel choice algorithm is quite simple:

  1. If the kernel is currently used, don't remove it;
  2. If the kernel is referenced by a bootloader, don't remove it (unless --destructive);
  3. If auxiliary files do not map to existing kernel, remove them;
  4. If --all is used, remove the kernel;
  5. If kernel is not within N newest kernels (where N is the argument to -n), remove it.

The program always derefences symlinks and counts real path references. Thus, a particular file will be removed only if all kernels referencing it are removed as well. This is especially important for shared kernel sources.

Bootloader support

In order to determine kernels currently used, eclean-kernel is supposed to read configuration files used by the bootloader. Right now, the following bootloaders are supported (and looked up in the following order):

  1. lilo,
  2. grub2,
  3. grub,
  4. yaboot.

There is also a pseudo-bootloader module called symlinks which assumes files symlinked to /boot/PREFIX and /boot/PREFIX.old are used.

By default, eclean-kernel uses the first bootloader from the above list for which a configuration file exists, and uses symlinks as a fallback. This can be changed using --bootloader argument.

Reporting bugs

Please report bugs either to the issue tracker or Gentoo Bugzilla. When reporting a bug, please attach the outputs of:

eclean-kernel -l
ls -l /boot /lib/modules/*

If relevant, please attach bootloader configuration files as well.