Gentoo Cheat Sheet/zh-cn
emerge — configuration — ebuild repository — dispatch-conf
world file — USE flags — ebuilds — profiles
upgrades — using testing packages — binary packages
tools — gentoolkit — eselect
Portage FAQ — cheat sheet — FAQ
This is a reference card of useful commands and tips for administrating Gentoo systems. Newcomers and grey beards alike are encouraged to add their helpful tips below.
Sync all repositories that are set to auto-sync including the Gentoo ebuild repository:
emaint --auto sync
emaint -a sync
Sync the Gentoo ebuild repository using the mirrors by obtaining a snapshot that is (at most) a day old:
emerge --sync now runs the emaint sync module with the
--auto option. See Portage's sync operation.
This not only syncs the repositories, it also updates the cache used by eix to perform queries. It may be preferable to configure portage to update the cache automatically.
列出已安装的软件包，并且带有版本号和使用的 overlay 名称：
To view the list of packages in the world set, along with their available versions, it is possible to use eix:
eix --world | less
To keep color in the output, use the
eix --color -c --world | less -R
In the following examples the www-client/firefox package will be used, but users should replace it with the package they want to install.
List what packages would be installed, without installing them:
emerge --pretend --verbose www-client/firefox
emerge -pv www-client/firefox
emerge --ask --verbose www-client/firefox
emerge -av www-client/firefox
Install a specific version of a package (use "\=" (backslash and equal sign) for shells that attach special meaning to the "=" character). For example:
emerge --ask =www-client/firefox-96.0.1
This will work temporarily, until the system is updated. During an update Portage will try to install the latest stable version of the package no matter which version is currently installed; whether the package was originally emerged via a preceding = operator or not.
To prevent Portage from automatically updating a package, add a line into a the /etc/portage/package.mask/package.mask file (create the file if it does not exist). Specify using the greater than operator (
>) prefix if it is an older package than latest stable or lesser than operator (
<) as a prefix if it is a newer one:
See /etc/portage/package.mask for more details on package masking.
Install without adding to the world file
Install a package without adding it to the world file:
emerge --ask --oneshot www-client/firefox
emerge -a1 www-client/firefox
Use emerge --deselect (or
-W option for short) to remove the specified package from the @world set (i.e. it indicate that the package is no longer wanted):
emerge --deselect www-client/firefox
Now run emerge --depclean (or
-c option for short). The
-p) option will have emerge display what actions would be taken, this must be reviewed to make sure no required packages would be removed:
emerge --pretend --depclean
If emerge --depclean has not been run in a while, it may try to remove many packages - caution is advised. Once it has been assured that emerge --depclean will only remove unneeded packages, run:
emerge --ask --depclean
--ask option is not really needed after a check via
--pretend, but is included in the previous example to help avoid "copy paste" mishaps.
Do not confuse the lower case
-cswitch, which is short for
--depclean(and is safe), with the upper case
-Cswitch which risks damaging the system and should only be used when absolutely required (see warning in following section).
To directly remove a package that no other packages depend on:
emerge --ask --verbose --depclean www-client/firefox
Calculating dependencies... done! >>> Calculating removal order... >>> These are the packages that would be unmerged: www-client/firefox selected: 68.5.0 protected: none omitted: none All selected packages: =www-client/firefox-68.5.0 >>> 'Selected' packages are slated for removal. >>> 'Protected' and 'omitted' packages will not be removed. Would you like to unmerge these packages? [Yes/No]
As a safety measure, depclean will not remove any packages unless all required dependencies have been resolved. As a consequence of this, it is sometimes necessary to first run:
emerge --ask --verbose --update --newuse --deep @world
-U) in place of
-N) to avoid rebuilds when the only changes are USE flags added to or dropped from the repository. Use the
-q) flag for more succinct execution:
emerge --ask --quiet --update --changed-use --deep @world
There is an
-C), but this is not recommended and can break the system if not used with caution. This should only ever be used if necessary, and once properly informed of what it does. This will break the system, or other software, if used on some packages. The correct way to remove packages in Gentoo is virtually always with the
--depcleanoption, as described above. This may sometimes be useful to temporarily remove a hard block though.
Upgrade all packages in the world set, their dependencies (
--deep), and packages that have USE flag changes (avoiding unnecessary rebuilds when USE changes have no impact):
emerge --ask --verbose --update --deep --changed-use @world
--newuse may be used in place of
--changed-use to make sure that all package use flags reflect the current state of those in the Gentoo repository, though this will entail more rebuilds. The
--with-bdeps=y can be used to update build time dependencies also.
Check for and rebuild missing libraries (not normally needed):
equery is part of app-portage/gentoolkit. Install it by issuing this command:
emerge -a gentoolkit
Tell which installed package provides a command using equery:
equery b `which vim`
qfile can provide a faster alternative to equery, if needed.
Tell which (not) installed package provides a command using e-file:
emerge -a app-portage/pfl
Tell which packages depend on a specific package (cat/pkg in the example) using equery:
equery d www-client/firefox
Get information about a package using eix:
Do not unemerge sys-libs/glibc. It is needed by nearly every other package. If it gets inadvertently removed, a rescue stick/disk may be required. It may be possible to fetch glibc after setting
Sometimes it's necessary to rebuild some packages for them to work properly. Here are some of the common rebuilds:
After installing a new kernel:
After upgrading to a new version of Go:
For using new libraries:
Manage configuration changes after an emerge completes:
After installations or updates
After updating perl-core packages:
Or if previous didn't help:
perl-cleaner --reallyall -- -av
For haskell packages:
Obtain descriptions and usage of the USE flag
X using euse:
euse -i X
Gather more information on euse by reading its manual page:
Show what packages have the
mysql USE flag:
equery hasuse mysql
Show what packages are currently built with the
mysql USE flag:
eix --installed-with-use mysql
Show what USE flags are available for a specific package:
equery uses <package-name>
Quickly add a required USE flag for a package install:
echo 'dev-util/cmake -qt5' >> /etc/portage/package.use
Important Portage files
- /etc/portage - primary configuration directory for Portage.
- /etc/portage/make.conf - Global settings (USE flags, compiler options).
- /etc/portage/package.use - USE flags of individual packages. Can also be a folder containing multiple files.
- /etc/portage/package.accept_keywords - Keyword individual packages; e.g. ~amd64, ~x86, or ∼arm.
- /etc/portage/package.license - Accepted licenses
- /etc/portage/profile/use.mask - for masking/unmasking locked use flags.
- /var/lib/portage/world - List of explicitly installed package atoms.
- /var/db/pkg - Contains information for every installed package a set of files about the installation.
genlop is a Portage log processor, also estimating build times when emerging packages.
Install app-portage/genlop by issuing:
emerge -a app-portage/genlop
Gather more information on genlop by reading its manual page:
View the last 10 emerges (installs):
genlop -l | tail -n 10
View how long emerging LibreOffice took:
genlop -t libreoffice
Estimate how long emerge -uND --with-bdeps=y @world will take:
emerge -pU @world | genlop --pretend
Watch the latest merging ebuild during system upgrades:
watch genlop -unc
app-eselect/eselect-repository can be installed by issuing:
emerge -a app-eselect/eselect-repository
List all existing overlays:
eselect repository list
List all installed overlays:
eselect repository list -i
Obtain root shell (if the current user is listed in the sudoers list):
Start the ssh daemon in the default runlevel at boot:
rc-update add sshd default
Start the sshd service now:
rc-service sshd start
Check if the sshd service is running:
rc-service sshd status
Restart the sshd service:
rc-service sshd restart
Stop the sshd service:
rc-service sshd stop
List services, their status, and the runlevels they belong to:
Show enabled services and the runlevels they belong to (not whether they are running or not, just if they are enabled):
Start the ssh daemon at boot:
systemctl enable sshd
Start the sshd service now:
systemctl start sshd
Check if the sshd service is running:
systemctl status sshd
Search packages in Portage by regular expressions
To search packages in Portage by regular expressions:
emerge -s "%^python$"
Generate metadata caches
Ebuild repositories vary from very small to very large in size. As a result they slow down the majority of Portage operations. That happens because overlays do not contain metadata caches. The cache is used to speed up searches and the building of dependency trees. A neat trick is to generate local metadata cache after syncing overlays.
This trick also works in conjunction with eix. eix-update can use metadata cache generated by emerge --regen to speed up things. To enable this, add the following variable to /etc/eixrc/00-eixrc:
Use qcheck to verify installed packages:
qcheck comes with app-portage/portage-utils and can be installed by running this command:
emerge -a app-portage/portage-utils
Learn more about qcheck by reading its manual page: