Search Term Reference

Table 2.1, “Quick guide to search terms” provides a brief summary of all the search terms provided by aptitude. A full description of each term can be found below.

Table 2.1. Quick guide to search terms

Long formShort formDescription
?=variable   Select the package bound to variable; see the section called “Explicit search targets”.
?not(pattern)!pattern Select any package that does not match pattern.
?action(action) ~aaction Select packages that have been marked for the given action (e.g., “install” or “upgrade”).
?all-versions(pattern)   Select packages whose versions all match pattern.
?and(term1, term2) term1 term2 Select any package that matches both term1 and term2.
?any-version(pattern)  Select packages for which at least one version matches pattern.
?archive(archive) ~Aarchive Select packages from the given archive (such as “unstable”).
?automatic~M Select packages that were automatically installed.
?bind(variable, pattern) ?variable:term-name[(args)] Selects anything if variable matches pattern; see the section called “Explicit search targets”.
?broken~b Select packages that have a broken dependency.
?broken-depType~BdepType Select package that have a broken dependency of the given depType.
?broken-depType(pattern)~DB[depType:]pattern Select packages that have a broken dependency of the given depType matching pattern.
?broken-reverse-depType(pattern)~RBdepType:pattern Select packages that a package matching pattern declares a broken dependency of type depType.
?conflicts(pattern) ~Cpattern Select packages that conflict with a package matching pattern.
?config-files~c Select packages that were removed but not purged.
?depType(pattern)~D[depType:]pattern Match packages that declare a dependency of type depType on a package matching pattern.
?description(description)~ddescription Select packages whose description matches description.
?essential~E Select essential packages, those with Essential: yes in their control files.
?false~F Select no packages.
?for variable: pattern  Select packages that match pattern with variable bound to the package being matched; see the section called “Explicit search targets”.
?garbage~g Select packages that are not required by any manually installed package.
?installed~iSelect installed packages.
?maintainer(maintainer)~mmaintainer Select packages maintained by maintainer.
?narrow(filter, pattern)~S filter pattern Select packages for which a single version matches both filter and pattern.
?name(name)~nname, name Select packages with the given name.
?new~N Select new packages.
?obsolete~o Match installed packages that cannot be downloaded.
?or(term1, term2)term1 | term2 Select packages that match term1, term2, or both.
?origin(origin)~Oorigin Select packages with the given origin.
?provides(pattern)~Ppattern Select packages that provide a package matching pattern.
?priority(priority)~ppriority Select packages with the given priority.
?reverse-depType(pattern)~R[depType:]pattern Select packages that are the targets of a dependency of type depType declared by a package matching pattern.
?reverse-broken-depType(pattern)~RBdepType:pattern Select packages that are the targets of a broken dependency of type depType declared by a package matching pattern.
?section(section)~ssection Select packages in the given section.
?source-package(name)  Select packages whose source package name matches the regular expression name.
?source-version(version)  Select packages whose source version matches the regular expression version.
?tag(tag)~Gtag Select packages that have the given debtags tag.
?true~T Select all packages.
?task(task)~ttask Select packages that are in the given task.
?upgradable~U Select packages that are installed and can be upgraded.
?user-tag  Select packages that are marked with a user-tag matching the regular expression user-tag.
?version(version)~Vversion Select packages whose version matches version (special values: CURRENT, CANDIDATE, and TARGET).
?virtual~v Select virtual packages.
?widen(pattern)~Wpattern Select versions for which pattern matches any version of the corresponding package, discarding local version restrictions.

name

Matches packages whose names match the regular expression name. This is the “default” search mode and is used for patterns that don't start with ~.

[Note]Note

To match packages whose names contain several different substrings, use the ?name term (described below); for instance, “?name(apti)?name(tude)”.

?=variable

Matches packages that correspond to the value of variable, which must be bound by an enclosing ?for. For instance, ?for x: ?depends( ?recommends( ?=x ) ) will match any package x that depends on a package which recommends x.

For instance, the following search expression matches packages that conflict with themselves:

Example 2.1.  Use of the ?= term.

?for x: ?conflicts(?=x)


See the section called “Explicit search targets” for more information.

?not(pattern), !pattern

Matches packages which do not match the term pattern. For instance, “?not(?broken)” selects packages that are not “broken”.

[Note]Note

To include a “!” in a regular expression, it must be “escaped” to prevent aptitude from considering it part of a NOT term: “~!”.

?and(term1, term2), term1 term2

Matches packages that match both term1 and term2.

?or(term1, term2), term1 | term2

Matches packages that match either term1 or term2.

[Note]Note

To use the character “|” in a regular expression, it must be “escaped” to prevent aptitude from creating an OR term from it: “~|”.

(pattern)

Matches pattern. For instance, “opengl (perl|python)” matches any package whose name contains opengl, and also contains either perl or python.

?action(action), ~aaction

Matches packages upon which the given action is going to be performed. action can be “install”, “upgrade”, “downgrade”, “remove”, “purge”, “hold” (tests whether a package has been placed on hold), or “keep” (tests whether a package will be unchanged).

Note that this only tests whether an action is actually queued up to be performed on a package, not whether it could be performed. Thus, for instance, ?action(upgrade) matches exactly those packages that you have already decided to upgrade, not packages which could be upgraded in the future (for that, use ?upgradable).

?all-versions(pattern)

Matches any package whose versions all match the given expression. Each version of a package will be separately tested against pattern, and the package will match if all of its versions match. Packages without versions, such as virtual packages, will always be matched by this search term.

This term may not be used in a context in which the versions to match against have already been narrowed, such as within ?depends or ?narrow. However, it may always be used within ?widen.

?any-version(pattern)

Matches a package if any one of its versions matches the enclosed term. This is the dual to ?all-versions.

This term may not be used in a context in which the versions to match against have already been narrowed, such as within ?depends or ?narrow. However, it may always be used within ?widen.

[Note]Note

This term is closely related to ?narrow. In fact, ?any-version(term1 term2) is exactly the same as ?narrow(term1, term2).

?archive(archive), ~Aarchive

Matches package versions which are available from an archive that matches the regular expression archive. For instance, “?archive(testing)” matches any package available from the testing archive.

?automatic, ~M

Matches packages which were automatically installed.

?bind(variable, pattern), ?variable:term-name[(args)]

Matches any package or version if the given pattern matches the package or version bound to variable, which must be defined in an enclosing ?for.

For instance, the following search expression will match any package x such that x depends on a package y which in turn depends on a package z such that x also depends directly on z.

Example 2.2. Use of the ?bind term


See the section called “Explicit search targets” for more information.

?broken, ~b

Matches packages that are “broken”: they have an unfulfilled dependency, predependency, breaks, or conflict.

?broken-depType, ~BdepType

Matches packages which have an unfulfilled (“broken”) dependency of the given depType. depType can be “depends”, “predepends”, “recommends”, “suggests”, “breaks”, “conflicts”, or “replaces”.

?broken-depType(pattern), ~DB[depType:]pattern

Matches packages with an unsatisfied dependency of type depType on a package matching pattern. depType may be any one of the dependency types listed in the documentation of ?broken-depType.

?conflicts(pattern), ~Cpattern

Matches packages which conflict with a package matching the given pattern. For instance, “?conflicts(?maintainer(dburrows@debian.org))” matches any package which conflicts with a package I maintain.

?config-files, ~c

Matches packages which have been removed, but whose configuration files remain on the system (ie, they were removed but not purged).

?depType(patterm), ~D[depType:]pattern

depType may be any one of the dependency types given in the documentation of ?broken-depType, as well as provides: for instance, ?depends(libpng3) will match any package that depends on libpng3. If the short form (~D) is used and depType is not present, it defaults to depends.

If depType is “provides”, matches packages that provide a package matching pattern (the equivalent of ?provides). Otherwise, matches packages which declare a dependency of type depType upon a package version which matches pattern.

?description(description), ~ddescription

Matches packages whose description matches the regular expression description.

?essential, ~E

Matches Essential packages.

?false, ~F

This term does not match any package. [15]

?for variable: pattern

Matches pattern, but the given variable may be used inside pattern to refer to the package or package version this term to.

You can use variable in two ways. To apply a ?-style term to the variable, write ?variable:term-name(args); for instance, ?x:depends(apt). In addition, the term ?=variable will select any package or version that matches the value of the given variable.

For instance, the following term will match any package x that both depends and recommends a second package y.

Example 2.3. Use of the ?for term

?for x: ?depends( ?for y: ?x:recommends( ?=y ) )


See the section called “Explicit search targets” for more information.

?garbage, ~g

Matches packages which are not installed, or which were automatically installed and are not depended upon by any installed package.

?installed, ~i

Matches package versions which are currently installed.

Since all versions are tested by default, this normally matches packages which are currently installed.

?maintainer(maintainer), ~mmaintainer

Matches packages whose Maintainer field matches the regular expression maintainer. For instance, “?maintainer(joeyh)” will find all packages maintained by Joey Hess.

?narrow(filter, pattern), ~S filter pattern

This term “narrows” the search to package versions matching filter. In particular, it matches any package version which matches both filter and pattern. The string value of the match is the string value of pattern.

?name(name), ~nname

Matches packages whose name matches the regular expression name. For instance, most of the packages that match “?name(^lib)” are libraries of one sort or another.

?new, ~N

Matches packages which are “new”.

?obsolete, ~o

This term matches any installed package which is not available in any version from any archive. These packages appear as “Obsolete or Locally Installed” in the visual interface.

?origin(origin), ~Oorigin

Matches package versions whose origin matches the regular expression origin. For instance, “!?origin(debian)” will find any unofficial packages on your system (packages not from the Debian archive).

?provides(pattern), ~Ppattern

Matches package versions which provide a package that matches the pattern. For instance, “?provides(mail-transport-agent)” will match all the packages that provide “mail-transport-agent”.

?priority(priority), ~ppriority

Matches packages whose priority is priority; priority must be extra, important, optional, required, or standard. For instance, “?priority(required)” matches packages whose priority is “required”.

?reverse-depType(pattern), ~R[depType:]pattern

depType may be either “provides” or one of the dependency types given in the documentation of ?broken-depType. If depType is not present, it defaults to depends.

If depType is “provides”, matches packages whose name is provided by a package version matching pattern. Otherwise, matches packages which a package version matching pattern declares a dependency of type depType upon.

?reverse-broken-depType(pattern), ?broken-reverse-depType(pattern), ~RB[depType:]pattern

depType may be either “provides” or one of the dependency types given in the documentation of ?broken-depType. If depType is not present, it defaults to depends.

Matches packages which a package version matching pattern declares an unsatisfied dependency of type depType upon.

?section(section), ~ssection

Matches packages whose section matches the regular expression section.

?source-package(name)

Matches packages whose source package name matches the regular expression name.

?source-version(version)

Matches packages whose source version matches the regular expression version.

?tag(tag), ~Gtag

Matches packages whose Tag field matches the regular expression tag. For instance, the pattern ?tag(game::strategy) would match strategy games.

For more information on tags and debtags, see http://debtags.alioth.debian.org.

?true, ~T

This term matches any package. For instance, “?installed?provides(?true)” matches installed packages which are provided by any package.

~ttask

Matches packages that appear in a task whose name matches the regular expression task.

?upgradable, ~U

This term matches any installed package which can be upgraded.

?user-tag(tag)

This term matches any package that is marked with a user-tag matching the regular expression tag.

?version(version), ~Vversion

Matches any package version whose version number matches the regular expression version, with the exceptions noted below. For instance, “?version(debian)” matches packages whose version contains “debian”.

The following values of version are treated specially. To search for version numbers containing these values, preface the value with a backslash; for instance, to find packages whose version number contains CURRENT, search for \CURRENT.

  • CURRENT matches the currently installed version of a package, if any.

  • CANDIDATE matches the version, if any, of the package that will be installed if you press + on the package or run aptitude install on it.

  • TARGET matches the version of a package that is currently targeted for installation, if any.

?virtual, ~v

Matches any package which is purely virtual: that is, its name is provided by a package or mentioned in a dependency, but no package of that name exists. For instance, “?vortial!?provides(?true)” matches packages which are virtual and are not provided by any package: ie, packages which are depended upon but do not exist.

?widen(pattern), ~Wpattern

Widens” the match: if the versions to match against have been limited by an enclosing term (such as ?depends), these limits are dropped. Thus, ?widen(pattern) matches a package version if pattern matches any version of that package.



[15] This is provided largely for symmetry with ?true.