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.

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-Status-Format, and Aptitude::UI::Package-Header-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.

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 Size6No The size of the package file containing the package.
%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 Size6No 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 “”.No Outputs the version of aptitude that is running, currently “”.
%NProgram NameThe length of the name.No Outputs the name of the program; usually “aptitude”.
%oDownload Size15No 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”.
%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.
%TTagged1No Outputs “*” if the package is tagged, nothing otherwise.[16]
%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 Version10No Outputs the currently installed version of the package, or <none> if the package is not currently installed.
%VCandidate Version10No 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 Change7No 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.


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.


Groups packages according to an extra data file describing a “hierarchy” of packages.

pattern(pattern [=> title][, ...])

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.

For instance, pattern(?maintainer() => \1) 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. For instance, pattern(?action(remove) => Packages Being Removed, ?true ||) will place packages that are being removed into a subtree, and place all the other packages at the current level. Any later grouping policies will apply to both sets of packages, of course.

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:

  • Installed

  • Not Installed

  • Security Updates

  • Upgradable

  • Obsolete

  • Virtual


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 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.

The available rules are:


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


Sorts packages by name.


Sorts packages by priority.


Sorts packages according to their version number.

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