An Introduction to Portage

Updated 7 November 2026

This page applies to Portage 3.0.82 and Calculate Utilities 3.8.

This page opens the Working with Portage series: it collects the basic concepts - repositories and ebuild, tree synchronization, search, package installation and removal, licenses, and typical Portage messages.

Welcome to Portage

Portage is the software management system that Calculate Linux adopted from Gentoo. Thanks to its flexibility and rich feature set, it is often called one of the best package management tools in Linux. Portage is written entirely in Python and Bash - scripting languages - so its work is open and understandable to the user.

Most users interact with Portage through the emerge command. This page does not duplicate its reference: the full list of options is given by the man page:

The ebuild repository

What is an ebuild

When the documentation talks about "packages", it means programs made available to the user through repositories - collections of ebuild files. Each such file contains all the information Portage uses to install, find, and control a program: its versions, dependencies, build flags, and source code addresses. The main collection of recipes is the gentoo repository in /var/db/repos/gentoo; the calculate repository with the packages, eclasses, and templates of the Calculate project lies in /var/db/repos/calculate.

When you ask Portage to do anything with a program, it relies on the ebuild files available in the system. That is why the tree must be updated regularly - otherwise Portage will not learn about new programs and security updates.

The five Calculate repositories

Unlike 'pure' Gentoo, the Calculate distribution is configured to work with five repositories at once:

• gentoo - a mirror of the Gentoo tree; it synchronizes not directly with the Gentoo servers but through the mirrors of the Calculate project (sync type calculate);
• calculate - packages, eclasses, and templates of Calculate itself;
• distros - distribution profiles (CLD, CLDX, CDS, and others);
• container - a repository for container builds in /var/calculate/repos/container;
• custom - a user repository in /var/calculate/repos/custom with masters calculate and gentoo - a ready-made base for your own packages, without third-party overlay managers.

The gentoo repository is designated as the main one (main-repo). Here is how Portage sees this setting - the Repositories section of the emerge --info output:

Repositories:

custom
    location: /var/calculate/repos/custom
    masters: calculate gentoo
    volatile: True

calculate
    location: /var/db/repos/calculate
    sync-type: calculate
    sync-uri: https://github.com/calculatelinux/calculate
    masters: gentoo
    priority: 50
    volatile: False

container
    location: /var/calculate/repos/container
    sync-type: git
    sync-uri: https://github.com/calculatelinux/container
    masters: calculate gentoo
    priority: 50
    volatile: True

distros
    location: /var/db/repos/distros
    sync-type: calculate
    sync-uri: https://github.com/calculatelinux/distros
    masters: calculate gentoo
    priority: 50
    volatile: False

gentoo
    location: /var/db/repos/gentoo
    sync-type: calculate
    sync-uri: https://github.com/calculatelinux/gentoo
    priority: 50
    volatile: False

The repository configuration lies in the files of the /etc/portage/repos.conf/ directory, which the distribution creates; they should not be edited by hand. Add your own repository with a NEW file in this directory - details on the Stepping aside from the official tree page. The full map of Portage working directories is in the Files and directories section.

Updating the tree

The standard way to update the repositories is the cl-update -s command, which performs synchronization only:

The same synchronization runs automatically on every full cl-update. Separately, you can choose which repositories to synchronize (the -r option) and enable a forced update of the search database (--force-eix-update). The help output shows the full set of options:

usage: cl-update [--stable [ON/OFF]] [--scan [ON/OFF]]
                 [--with-bdeps [ON/OFF/AUTO]] [-m MIRROR_URL]
                 [--repo-update REPOSITORY URL] [-o [ON/OFF/AUTO]]
                 [-s [ON/OFF]] [-p [ON/OFF]] [-r REPOSITORIES] [-e [ON/OFF]]
                 [-C [ON/OFF]] [--force-fix [ON/OFF]]
                 [--ignore-level [ON/OFF]] [--force-level LEVEL]
                 [--rebuild-world | --merge-world | --update-world]
                 [--force-check-sign | --skip-check-sign | --auto-check-sign]
                 [--force-egencache | --skip-egencache | --auto-egencache]
                 [--force-eix-update | --skip-eix-update | --auto-eix-update]
                 [-R [ON/OFF]] [--wait-another-update [ON/OFF]]
                 [--schedule [ON/OFF]] [-1 [ON/OFF/AUTO]]
                 [--clean-pkg [ON/OFF]] [--branch REFS] [-T TEMPLATES]
                 [-v [ON/OFF]] [--usenew-conf | --skip-conf | --dispatch-conf]
                 [--exclude exclude] [-f]

Installing and removing programs

Searching for programs

The easiest way is the built-in emerge search: by default --search finds packages whose name matches the query fully or in part. For example, searching for packages with the word "nano":

[ Results for search key : nano ]
Searching...

*  app-editors/nano
      Latest version available: 9.2
      Latest version installed: [ Not Installed ]

*  www-apps/nanoc-spec [ Masked ]
      Latest version available: 0.0.2-r1
      Latest version installed: [ Not Installed ]
      Size of files: 7 KiB
      Homepage:      https://nanoc.app/
      Description:   Provides Nanoc::Spec, containing functionality for writing tests for Nanoc
      License:       MIT

[ Applications found : 15 ]

To search names and descriptions at once, use the --searchdesc option (short form -S):

The answer for every match lists the available and installed versions, the size, the homepage, the description, and the license - the fields are labeled explicitly. For a quick search across the tree, the eix utility is more convenient - it has its own page, Fast search with eix.

Installation

Once the program you need is found, installation is one step away. Since many programs depend on each other, installing one package can pull in dozens of dependencies. Do not worry: Portage deals with them on its own. First it is useful to look at the installation plan without actually installing: the -p option (--pretend) prints the packages that will be installed, in build order:

These are the packages that would be merged, in order:

Calculating dependencies ... done!
Dependency resolution took 2.39 s (backtrack: 0/20).

[binary  N g   ] app-editors/nano-9.2::gentoo  USE="ncurses nls (unicode) -debug -justify -magic -minimal -spell -verify-sig" 694 KiB

Total: 1 package (1 new, 1 binary), Size of downloads: 694 KiB

Reading the output: in a package line, the USE flags follow the name - enabled ones without a prefix, disabled ones with a minus; the download size is given at the end of the line. The final line totals the packages and the download volume.

To install the package, drop -p and add -a (--ask) - Portage will ask for confirmation before starting:

During installation Portage downloads the sources from the internet when needed and keeps them in the /var/calculate/distfiles directory (the DISTDIR variable), then unpacks, builds, and installs the package. If you only need the sources downloaded, without installation, add -f (--fetchonly):

Documentation of installed packages

Many programs ship with their own documentation; whether it is installed often depends on the doc USE flag. You can check whether a package has this flag in the USE= line of the emerge -pv output shown above.

It is better to enable the flag for individual packages in /etc/portage/package.use/ rather than globally - otherwise documentation will be pulled into every build. This is described in detail in the USE flags section.

After installation the documentation usually lies in a subdirectory of /usr/share/doc/ named after the package and its version:

The reliable way to get the exact list of documentation is a query to the installed files database with equery (from the app-portage/gentoolkit package):

/usr/share/doc/eselect-1.4.32/AUTHORS.bz2
/usr/share/doc/eselect-1.4.32/ChangeLog.bz2
/usr/share/doc/eselect-1.4.32/NEWS.bz2
/usr/share/doc/eselect-1.4.32/README.bz2

The --filter option can display other categories of files as well; details are in the Additional Portage functionality section.

Removing programs

Removing a program safely means first telling Portage that you no longer need it:

The command removes the package from the list of explicit installs, after which it becomes a candidate for depclean. By itself, --deselect does not delete any files; the --depclean option (short form -c) frees the system from the package and from the dependencies that have become unneeded:

The list of explicitly installed packages is kept in the /var/lib/portage/world file. In Calculate its contents are formed not by the user alone: the list is assembled by distribution templates from /var/db/repos/calculate/profiles/templates/6_ac_update_sync/world/create/, which is why the file begins with a service header listing the templates processed. Such a template looks like this:

# Calculate name=world format=world

#?in(os_linux_pkglist, calculate)!=#
media-fonts/terminus-font
sys-apps/busybox
sys-apps/calculate-toolkit
#sys-apps/ifplugd
sys-apps/less

Lines that begin with # are not added to the list. The template mechanism is described on the Templates page.

Updating the system

So that the system stays in order and keeps receiving security updates, it must be updated regularly. The standard Calculate route is the cl-update command: it synchronizes the repositories, updates packages, applies templates, and protects configuration files from being overwritten:

For targeted control, you can work with the tools of Portage itself. To update installed packages, use emerge with the -u (--update), -D (--deep), and -N (--newuse) options:

With -D, Portage also looks for newer versions of the installed dependencies; without it, only the versions of explicitly installed packages are checked - those listed in /var/lib/portage/world - while their dependencies are left alone. That is why -D is applied almost always. The -N option forces a rebuild of the packages whose USE flags have changed since installation - you need it after editing USE. Both variants (cl-update and emerge -uDN @world) work; for regular updates of the distribution, cl-update is the standard choice.

Meta-packages

Some packages in the tree contain no working program of their own - they exist so that a set of related components can be installed with a single command. For example, kde-plasma/plasma-meta installs the Plasma environment, pulling the Plasma packages in as dependencies.

Removing a meta-package with a single emerge --deselect achieves little: its dependencies stay in the system. Portage can clean out orphaned dependencies, but the availability of programs is determined dynamically, so before the cleanup you must fully update the system (with all the changes made by USE flag edits), then remove the orphaned packages and, if necessary, rebuild the applications that were dynamically linked against the removed packages and no longer need them. Both commands:

Licenses

Each ebuild specifies the license of the package in the LICENSE variable - you can see it in the search output as well. An important caveat: LICENSE in an ebuild is a guide for developers and users, not a legal statement; it does not guarantee an exact match with the license of every installed file.

The ACCEPT_LICENSE variable manages the permitted licenses. In Calculate it is set to * by default, that is, licenses are not restricted at all - installing a package with any license is allowed. The mechanism itself remains the standard one for Portage.

The value of ACCEPT_LICENSE is a list of accepted and rejected licenses: a name with a minus prefix forbids installation. License groups are written with the @ prefix:

• @FREE - free licenses approved by the free software organizations or following the free software definition;
• @BINARY-REDISTRIBUTABLE - licenses that allow the distribution of binary packages;
• @EULA - licenses that require agreeing to the text of the end-user license agreement.

The license texts lie in the /var/db/repos/gentoo/licenses/ directory, and the composition of the groups in the /var/db/repos/gentoo/profiles/license_groups file: each line starts with the group name in capital letters, followed by the licenses separated by spaces; a group may include other groups - they are listed with the @ prefix.

You can tighten the policy, for example to allow everything except EULA agreements - for that, the line is added to the user file /etc/portage/make.conf/custom: ACCEPT_LICENSE="* -@EULA". Such a setting will also accept non-free programs and non-free documentation. How to set build variables and where the configuration files live - see the Configuring through variables section.

Individual exceptions are written to the /etc/portage/package.license file (the user creates it): first the full package name, then the license or group. For example, this is how the firmware license is accepted:

# Allow linux-firmware firmware under the redistribution license
sys-kernel/linux-firmware @BINARY-REDISTRIBUTABLE

Note: allowing a license for one package does not extend to other packages with the same license - each one is specified separately.

If Portage complains

The wording of the Portage messages and the package versions in this section's examples are illustrative: the exact text and numbers on your system may differ.

Slots, virtuals, branches, architectures, profile

Portage supports many features that other package managers do not offer. What follows are the basic concepts, without the details.

Different versions of one package can coexist in the system. Where other distributions create versioned names for this (gtk+2 and gtk+3), Portage uses slots (SLOT): an ebuild declares a slot for its version, and ebuilds of different slots do not conflict. For example, the gtk+ package has ebuilds with SLOT="2" and SLOT="3".

Some packages offer the same functionality in different implementations: metalogd, sysklogd, and syslog-ng are all system logging services. An application that needs "one of the logging services" cannot depend on one concrete implementation: the others are no worse. For such cases Portage has virtuals: every logger is listed as an alternative of the virtual package virtual/logger, and applications depend on the latter. Installing a virtual pulls in one of the implementations, which Portage chooses; if a logger is already installed, the virtual counts as satisfied.

The programs of the tree are distributed across branches. By default the system accepts only the packages marked stable. Most programs newly added to the tree land in the testing branch (~arch): their ebuilds are visible in the tree, but Portage will not install them until the package is moved to the stable branch. Enabling individual testing packages is described in the Mixing branches section.

Not every program is available for every architecture: it may not work on some of them, need additional testing, or simply have never been checked by a maintainer.

Every system follows a profile - a set of settings that stores, among other things, the list of packages required for normal operation. In Calculate the profile is set by the distros repository (for CLD that is distros:CLD/amd64/20), which stands above the base Gentoo profile. You cannot switch the profile with eselect: the binary packages of the mirror and the world templates depend on it, and switching would damage the distribution. The configuration is done with USE flags, keywords, and masks in the files under /etc/portage/.

Blocked packages

An ebuild has dependency fields: a build-time dependency is declared in DEPEND, a run-time dependency in RDEPEND. If one of the dependencies explicitly marks a package or a virtual as incompatible, a block appears. The warning looks like this (it is usually visible with --pretend):

[ebuild  N     ] <package-A>
[blocks B      ] <package-A> ("<package-A>" is blocking <package-B>)

* Error: The above package list contains packages which cannot be
 * installed at the same time on the same system.

(<package-A>:0/0::gentoo, ebuild scheduled for merge) pulled in by
    <package-A>

(<package-B>:0/0::gentoo, installed) pulled in by
    <package-B> required by @selected

New versions of Portage deal with minor blocks on their own, but some conflicts require a manual decision. The options: give up installing the disputed package, or remove the conflicting one with emerge --deselect …. It is better not to remove by force but to tell Portage that the package is no longer needed: then, after depclean, it leaves both the world list and the system.

Sometimes the block is defined by an exact version atom, for example <media-video/mplayer-1.0_rc1-r2; in that case the block is lifted by updating the conflicting package to a newer version. A rare case is two not-yet-installed packages blocking each other: find out why both are needed - usually one is enough. If both are truly needed, report this to the developers of the distribution.

Masked packages

When you try to install a package that is unavailable to the system, Portage reports the masking:

!!! all ebuilds that could satisfy "bootsplash" have been masked.

There is always a reason for the masking:

You can lift the mask for a specific package with your own keywords and masks in /etc/portage/package.accept_keywords/ and /etc/portage/package.unmask/ - see Mixing branches.

Required USE flag changes

Sometimes the package being installed requires a dependency to be built with a specific USE flag. On Calculate, --autounmask is already enabled in EMERGE_DEFAULT_OPTS, so Portage itself offers a ready line for the package.use file:

The following USE changes are necessary to proceed:
#required by app-text/happypackage-2.0, required by happypackage (argument)
>=app-text/feelings-1.0.0 test

Without --autounmask, the same situation turns into an error about missing built variants:

emerge: there are no ebuilds built with USE flags to satisfy "app-text/feelings[test]".
!!! One of the following packages is required to complete your request:
- app-text/feelings-1.0.0 (Change USE: +test)
(dependency required by "app-text/happypackage-2.0" [ebuild])
(dependency required by "happypackage" [argument])

In the example, the package app-text/happypackage needs app-text/feelings built with USE="test", while the system does not have that flag enabled. The solution: add the required flag to the package in /etc/portage/package.use/ (the custom stub file is already there) or, less commonly, globally to the USE variable in the /etc/portage/make.conf/custom file. In detail - the USE flags section.

No such package

emerge: there are no ebuilds to satisfy ">=sys-devel/gcc-3.4.2-r4".

!!! Problem with ebuild sys-devel/gcc-3.4.2-r2
!!! Possibly a DEPEND/*DEPEND problem.

The application being installed depends on a package that is unavailable to the system. If the system does not mix branches, this should not happen - it is an error in the tree: check against the list of known errors and, if necessary, report a new one to the developers.

Ambiguous package name

[ Results for search key : listen ]
[ Applications found : 2 ]

*  dev-tinyos/listen [ Masked ]
      Latest version available: 1.1.15
      Latest version installed: [ Not Installed ]
      Size of files: 10,032 kB
      Homepage:      http://www.tinyos.net/
      Description:   Raw listen for TinyOS
      License:       BSD

*  media-sound/listen [ Masked ]
      Latest version available: 0.6.3
      Latest version installed: [ Not Installed ]
      Size of files: 859 kB
      Homepage:      http://www.listen-project.org
      Description:   A Music player and management for GNOME
      License:       GPL-2

!!! The short ebuild name "listen" is ambiguous. Please specify
!!! one of the above fully-qualified ebuild names instead.

The chosen name matches several packages from different categories. The options are already listed in the message above - specify the full name with the category.

Circular dependencies

!!! Error: circular dependencies:

ebuild / net-print/cups-1.1.15-r2 depends on ebuild / app-text/ghostscript-7.05.3-r1
ebuild / app-text/ghostscript-7.05.3-r1 depends on ebuild / net-print/cups-1.1.15-r2

Two (or more) packages being installed depend on each other, and therefore cannot be installed. Usually this is an error in one of the packages of the tree: after a while, update the tree and try again; check against the list of known errors and report a new one if necessary.

Fetch error

!!! Fetch failed for sys-libs/ncurses-5.4-r5, continuing...
(...)
!!! Some fetch errors were encountered.  Please see above for details.

Portage could not download the sources of the specified package and will try to continue installing the rest (where that is possible). The causes: a mirror was synchronized incorrectly, the ebuild points to a wrong address, or the source server is unavailable. Repeat the attempt in an hour - if the error remains, report it to the developers.

System profile protection

!!! Trying to unmerge package(s) in system profile. 'sys-apps/portage'
!!! This could be damaging to your system.

You are asking to remove a package from the system's base set: it is marked as required in the profile and should not be removed.

Digest verification failure

>>> checking ebuild checksums
!!! Digest verification failed:

This is a sign of a problem in the tree itself - most often a mistake when adding the ebuild. Do not try to recreate the manifest yourself: calling the ebuild utility with the manifest command will not fix the situation and is more likely to worsen it (this low-level utility is described in detail in the Using ebuild section). Wait an hour or two: the error has probably already been noticed, and the fix will reach the mirrors soon. If that does not help - report it to the developers, and after the fix update the tree to get the correct checksums.

See also

• USE flags
• Portage features
• Environment variables
• Files and directories
• Configuring through variables
• Mixing branches
• Additional Portage functionality
• Stepping aside from the official tree
• Using ebuild