Customizing the package list

Customizing how packages are displayed
Customizing the package hierarchy
Customizing how packages are sorted

The package list can be heavily customized: how packages are displayed, how the package hierarchy is formed, how packages are sorted, and even how the display is organized are all open to change.

Customizing how packages are displayed

This section describes how to configure the contents and format of the package list, status line, and header line, as well as the output of aptitude search.

The format of each of these locations is defined by a format string. A format string is a string of text containing %-escapes such as %p, %S, and so on. The resulting output is created by taking the text and replacing the %-escapes according to their meanings (given below).

A %-escape can either have a fixed size, in which case it is always replaced by the same amount of text (with extra space characters added to fill it out as necessary), or it can be expandable, meaning that it takes up the space that is not claimed by fixed-size columns. If there are several expandable columns, the extra space is divided evenly between them.

All %-escapes come with a default size and/or expandability. The size of a %-escape can be changed by writing it between the % and the character identifying the escape; for instance, %20V generates the candidate version of the package, 20 characters wide. Placing a question mark (?) between the % and the character identifying the escape causes the column's basic width to vary depending on its content. Note that the resulting columns might not line up vertically!

If you want a particular %-escape to be expandable, even though it normally has a fixed width, place a pound sign (ie, #) immediately after it. For instance, to display the candidate version of a package, no matter how long it is, use the format string %V#. You can also place # after something that is not a %-escape; aptitude will expand the text preceding the # by inserting extra spaces after it.

In summary, the syntax of a %-escape is:


The configuration variables Aptitude::UI::Package-Display-Format, Aptitude::UI::Package-Header-Format, and Aptitude::UI::Package-Status-Format define the default formats the package list, the header at the top of the package list, and the status line below the package list respectively. To change how the results of an aptitude search command are displayed, use the -F option.

The following %-escapes are available in format strings:


Some of the descriptions below refer to the package. In the GUI, this is either the package being displayed or the currently selected package; in the command-line search, this is the package being displayed.

EscapeNameDefault sizeExpandableDescription
%%Literal %1No This is not really an escape; it simply inserts a percent sign into the output at the point at which it occurs.
%#numberParameter ReplacementVariableNo In some circumstances, a display format string will have parameters: for instance, in the command-line search, the groups matched by the search are used as parameters when displaying the result. This format code will be replaced by the parameter indicated by number.
%aAction Flag1No A single-character flag summarizing any action to be performed on the package, as described in Figure 2.10, “Values of the action flag”.
%AAction10No A somewhat more verbose description of the action to be performed on the package.
%BBroken Count12No If there are no broken packages, produces nothing. Otherwise, produces a string such as Broken: 10 describing the number of broken packages.
%cCurrent State Flag1No A single-character flag summarizing the current state of the package, as described in Figure 2.9, “Values of the current state flag”.
%CCurrent State11No A more verbose description of the current state of the package.
%dDescription40Yes The package's short description.
%DPackage Size8No The size of the package file containing the package.
%EArchitecture10No Outputs the string of the architecture, for example amd64.
%eSource30No Outputs the source package, for example aptitude for aptitude-doc-en.
%HHostname15No The name of the computer on which aptitude is running.
%iPin priority4No Displays the highest priority assigned to a package version; for packages, displays the priority of the version which will be forced to be installed (if any).
%IInstalled Size8No The (estimated) amount of space the package takes up on disk.
%mMaintainer30Yes The maintainer of the package.
%MAutomatic Flag1No If the package is automatically installed, outputs A; otherwise, outputs nothing.
%nProgram VersionThe length of 0.8.5.No Outputs the version of aptitude that is running, currently 0.8.5.
%NProgram NameThe length of the name.No Outputs the name of the program; usually aptitude.
%oDownload Size17No If no packages are going to be installed, outputs nothing. Otherwise, outputs a string describing the total size of all the package files which will be installed (an estimate of how much needs to be downloaded); for instance, DL size: 1000B.
%OOrigin30No Outputs a string of the origin of the package, for example Debian:unstable [amd64].
%pPackage Name30Yes Outputs the name of the package. When a package is displayed in a tree context, the name of the package will be indented, if possible, according to its depth in the tree.
%PPriority9No Outputs the priority of the package.
%rReverse Depends Count2No Outputs the approximate number of installed packages which depend upon the package.
%RAbbreviated Priority3No Outputs an abbreviated description of the package's priority: for instance, Important becomes Imp.
%sSection10No Outputs the section of the package.
%STrust Status1No If the package is untrusted, displays the letter "U".
%tArchive10Yes The archive in which the package is found.
%TTagged (and user-tags)30No

Outputs * if the package is tagged, nothing otherwise.[19]

This field also includes user-tags.

%uDisk Usage Change30No If the scheduled actions will alter the amount of space used on the disk, outputs a description of the change in disk space; for instance, Will use 100MB of disk space.
%vCurrent Version14No Outputs the currently installed version of the package, or <none> if the package is not currently installed.
%VCandidate Version14No Outputs the version of the package which would be installed if PackageInstall (+) were issued on the package, or <none> if the package is not currently available.
%ZSize Change9No Outputs how much additional space will be used or how much space will be freed by installing, upgrading, or removing a package.

Customizing the package hierarchy

The package hierarchy is generated by a grouping policy: rules describing how the hierarchy should be built. The grouping policy describes a pipeline of rules; each rule can discard packages, create sub-hierarchies in which packages reside, or otherwise manipulate the tree. The configuration items Aptitude::UI::Default-Grouping and Aptitude::UI::Default-Preview-Grouping set the grouping policies for newly created package lists and preview screens, respectively. You can set the grouping policy for the current package list by pressing G.

The grouping policy is described by a comma-separated list of rules: rule1,rule2,.... Each rule consists of the name of the rule, possibly followed by arguments: for instance, versions or section(subdir). Whether arguments are required and how many arguments are required (or allowed) depends on the type of rule.

Rules can be non-terminal or terminal. A non-terminal rule will process a package by generating some part of the hierarchy, then passing the package on to a later rule. A terminal rule, on the other hand, will also generate part of the tree (typically items corresponding to the package), but does not pass its package to a later rule. If no terminal rule is specified, aptitude will use the default rule, which is to create the standard package items.


Groups packages according to the action scheduled on them; packages that are not upgradable and will be unchanged are ignored. This is the grouping that is used in preview trees.


Groups packages according to their architecture.


This is a terminal rule.

Creates standard package items which can be expanded to reveal the dependencies of the package.


Include only packages for which at least one version matches pattern.

If pattern is missing, no packages are discarded. This is a backwards compatibility feature and may be removed in the future.


Groups packages based on the first character of their name.

To be precise, it is not always the first letter -- for packages starting with lib* the name of the group is liba, libb, ... like in Debian FTPs.

mode can be one of the following:


Group based on the binary package name. This is the default if no mode is specified.

Example 2.7. Grouping policy firstchar or firstchar(binary)

With the source package dpkg as an example, the binary packages dselect, dpkg and dpkg-dev would be grouped under d, while libdpkg-dev and libdpkg-perl would be added to the libd group.


Group based on the source package name.

This is useful for example when browsing packages coming from the same source package (source grouping policy) within large collections (examples: all installed packages, all upgradable packages, all packages from "main" section), to add an intermediate grouping step. In this way, one can for example emulate the hierarchy of FTPs (try grouping: "section(topdir),firstchar(source),source").

Example 2.8. Grouping policy firstchar(source)

Again, with the source package dpkg as an example, all the binary packages dselect, dpkg, dpkg-dev, libdpkg-dev and libdpkg-perl would be grouped under d.

pattern(pattern [=> title] [{ policy }] [, ...])

A customizable grouping policy. Each version of every package is matched against the given patterns. The first match found is used to assign a title to the package; packages are then grouped by their title. Strings of the form \N that occur in title will be replaced by the Nth result of the match. If title is not present, it is assumed to be \1. Note that packages which do not match any patterns will not appear in the tree at all.

Example 2.9. Use of pattern to group packages by their maintainer

pattern(?maintainer() => \1)

The example above will group packages according to their Maintainer field. The policy pattern(?maintainer()) will do the same thing, as the absent title defaults to \1.

Instead of => title, an entry may end with ||. This indicates that packages matching the corresponding pattern will be inserted into the tree at the same level as the pattern grouping, rather than being placed in subtrees.

Example 2.10.  Use of pattern with some packages placed at the top level

pattern(?action(remove) => Packages Being Removed, ?true ||)

The example above will place packages that are being removed into a subtree, and place all the other packages at the current level, grouped according to the policies that follow pattern.

By default, all the packages that match each pattern are grouped according to the rules that follow the pattern policy. To specify a different policy for some packages, write the policy in braces ({}) after the title of the group, after the ||, or after the pattern if neither is present. For instance:

Example 2.11.  Use of the pattern grouping policy with sub-policies

pattern(?action(remove) => Packages Being Removed {}, ?action(install) => Packages Being Installed, ?true || {status})

The policy in the above example has the following effects:

  • Packages that are being removed are placed into a subtree labeled Packages Being Removed; the grouping policy for this subtree is empty, so the packages are placed into a flat list.

  • Packages that are being installed are placed into a subtree labeled Packages Being Installed and grouped according to the policies that follow pattern.

  • All remaining packages are placed at the top level of the tree, grouped according to their status.

See the section called “Search patterns” for more information on the format of pattern.


Groups packages according to their priority.


Groups packages according to their Section field.

mode can be one of the following:


Group based on the whole Section field, so categories like non-free/games will be created. This is the default if no mode is specified.


Group based on the part of the Section field before the first / character; if this part of the Section is not recognized, or if there is no /, the first entry in the list Aptitude::Sections::Top-Sections will be used instead.


Group based on the part of the Section field after the first / character, if it is contained in the list Aptitude::Sections::Top-Sections. If not, or if there is no /, group based on the entire Section field instead.


Group based on the part of the Section field after the first / character, if the portion of the field preceding it is contained in the list Aptitude::Sections::Top-Sections; if not, or if there is no /, the entire field will be used. If there are multiple / characters in the portion of the field that is used, a hierarchy of groups will be formed. For instance, if games is not a member of Aptitude::Sections::Top-Sections, then a package with a section of games/arcade will be placed under the top-level heading games, in a sub-tree named arcade.

If passthrough is present, packages which for some reason lack a true Section (for instance, virtual packages) will be passed directly to the next level of grouping without first being placed in sub-categories.


Groups packages into the following categories:

  • Security Updates

  • Upgradable

  • New

  • Installed

  • Not Installed

  • Obsolete and Locally Created

  • Virtual


Groups packages according to their source package name.


Groups packages according to the Tag information stored in the Debian package files. If facet is provided, then only tags corresponding to that facet will be displayed, and packages lacking this facet will be hidden; otherwise, all packages will be displayed at least once (with tagless packages listed separately from packages that have tags).

For more information on debtags, see


Creates a tree called Tasks which contains the available tasks (information on tasks is read from debian-tasks.desc in the package tasksel). The rule following task will create its categories as siblings of Tasks.


This is a terminal rule.

Creates standard package items which can be expanded to reveal the versions of the package.

Customizing how packages are sorted

By default, packages in the package list or in the output of aptitude search are sorted by name. However, it is often useful to sort them according to different criteria (for instance, package size), and aptitude allows you to do just that by modifying the sorting policy.

Like the grouping policy described in the previous section, the sorting policy is a comma-separated list. Each item in the list is the name of a sorting rule; if packages are equal according to the first rule, the second rule is used to sort them, and so on. Placing a tilde character (~) in front of a rule reverses the usual meaning of that rule. For instance, priority,~name will sort packages by priority, but packages with the same priority will be placed in reverse order according to name.

To change the sorting policy for an active package list, press S. To change the default sorting for all package lists, set the configuration option Aptitude::UI::Default-Sorting. To change the sorting policy for aptitude search, use the --sort command-line option.

The available rules are:


Sorts packages by the estimated amount of size they require when installed.


Sorts packages by the change in the installed size (estimated amount of size required when installed), comparing the current version (if installed) and the candidate version to be installed, upgraded or removed.


Sorts packages by the size of the package.


Sorts packages by name.


Sorts packages by priority.


Sorts packages according to their version number.

[19] Currently tagging is not supported; this escape is for future use.