From Gentoo Wiki
Jump to: navigation, search

egencache is a tool that rebuilds metadata information for the Portage tree. It is built into Portage and therefore comes installed on every Gentoo system.

Metadata for the Portage tree comes included in Portage tarballs and, in most circumstances, can be re-downloaded by running an emerge --sync. It will not be downloaded when using a CVS or git checkout as the Portage sync method, which is more easily possible using repos.conf.


Every Gentoo system should have egencache installed. Run a quick test by issuing the the --help option as seen in the usage section below.

If usage instructions are not displayed to the terminal there is certainly a problem. It is possible to (re)install Portage by following the Portage installation instructions.



Use the -h/--help option to see the capabilities of egencache:

root #egencache --help
usage: egencache [options] <action> ... [atom] ...

optional arguments:
  -h, --help            show this help message and exit

  --update              update metadata/md5-cache/ (generate as necessary)
                        update the use.local.desc file from metadata.xml
  --update-changelogs   update the ChangeLog files from SCM logs
                        update package description index
  --update-manifests    update manifests

Common options:
  --repo REPO           name of repo to operate on
  --config-root PORTAGE_CONFIGROOT
                        location of portage config files
  --gpg-dir GPG_DIR     override the PORTAGE_GPG_DIR variable
  --gpg-key GPG_KEY     override the PORTAGE_GPG_KEY variable
  --portdir PORTDIR     override the PORTDIR variable (deprecated in favor of
  --portdir-overlay PORTDIR_OVERLAY
                        override the PORTDIR_OVERLAY variable (deprecated in
                        favor of --repositories-configuration)
  --repositories-configuration REPOSITORIES_CONFIGURATION
                        override configuration of repositories (in format of
  --sign-manifests <y|n>
                        manually override layout.conf sign-manifests setting
  --strict-manifests <y|n>
                        manually override "strict" FEATURES setting
  --thin-manifests <y|n>
                        manually override layout.conf thin-manifests setting
  --tolerant            exit successfully if only minor errors occurred
                        do not use the EGENCACHE_DEFAULT_OPTS environment
  --write-timestamp     write metadata/timestamp.chk as required for rsync

--update options:
  --cache-dir CACHE_DIR
                        location of the metadata cache
  -j JOBS, --jobs JOBS  max ebuild processes to spawn
  --load-average LOAD_AVERAGE
                        max load allowed when spawning multiple jobs
  --rsync               enable rsync stat collision workaround for bug 139134
                        (use with --update)

--update-use-local-desc options:
  --preserve-comments   preserve the comments from the existing use.local.desc
  --use-local-desc-output ULD_OUTPUT
                        output file for use.local.desc data (or '-' for

Rebuilding the metadata cache

In order to rebuild the metadata cache on a system issue the following command:

root #egencache --jobs=9 --update --repo gentoo

Adjust the number of jobs to be appropriate to each system. The "safe" metric to use with jobs will depend on the processor and system load; if there is no load on the system use the metric of one job per processor thread plus one. In a quad core processor that has two threads per core the equation would result in 9 being set for jobs (2*4+1). In the example above 9 jobs are used as the example.

Rebuilding the MD5 cache can take quite some time. If running the egencache command hangs for a while just wait it out. As with most Linux commands, if it does not return an error then it has not finished the job. (Example: 12 minutes on i7 with 9 jobs on 2016-06-10)


Simply put: removing Portage is a bad idea. Do not do it.

See also

  • elogv - A curses-based tool that parses the contents of elogs created by Portage.