Search term reference

Table 2.3, “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.3. 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(pattern1, pattern2) pattern1 pattern2 Select any package that matches both pattern1 and pattern2.
?any-version(pattern)  Select packages for which at least one version matches pattern.
?architecture(architecture) ~rarchitecture Select packages for the given architecture (such as amd64, or all). Special values: native and foreign.
?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.
?exact-name(name)  Select packages named name.
?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.
?multiarch(multiarch)  Select packages with a multi-arch capability of multiarch (that is, either foreign, same, allowed, or none).
?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(pattern1, pattern2)pattern1 | pattern2 Select packages that match pattern1, pattern2, 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.
?term(keyword)  Full-text search for packages that contain the given keyword.
?term-prefix(keyword)  Full-text search for packages that contain a keyword that begins with the given keyword.
?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) will match any package whose name contains both apti and 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.2.  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 pattern pattern. For instance, ?not(?broken) selects packages that are not broken.

[Note]Note

To include a ! in a search string, it must be escaped by placing a tilde (~) in front of it; otherwise, aptitude will consider it to be part of a ?not term. For instance, to select packages whose description contains extra!, use ?description(extra~!).

?and(pattern1, pattern2), pattern1 pattern2

Matches packages that match both pattern1 and pattern2.

?or(pattern1, pattern2), pattern1 | pattern2

Matches packages that match either pattern1 or pattern2.

[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 pattern. 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(pattern1 pattern2) is exactly the same as ?narrow(pattern1, pattern2).

?architecture(architecture), ~rarchitecture

Matches package versions for the given architecture. For instance, ?architecture(amd64) matches amd64 packages, while ?architecture(all) matches arch-independent packages. Also accepts the special values native and foreign.

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

Example 2.3. Use of the ?bind term

?for x: ?depends(?depends(?for z: ?bind(x, ?depends(?=z))))

?for x: ?depends(?depends(?for z: ?x:depends(?=z)))


The two search patterns in the above example both 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. The first pattern uses ?bind directly, while the second one uses an equivalent shorthand syntax.

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(pattern), ~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.

?exact-name(name)

Matches packages named name. This is similar to ?name, but the name must match exactly. For instance, the following pattern will match only the package apt; with ?name, it would also match aptitude, uvccapture, etc.

Example 2.4. Use of the ?exact-name term

?exact-name(apt)


?false, ~F

This term does not match any package. [18]

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

?multiarch(multiarch)

Matches packages with the multi-arch capability specified by multiarch. For instance, ?multiarch(foreign) will find all packages which can satisfy dependencies of packages for another architecture. ?multiarch(none) will select packages with no multi-arch capability.

?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: that is, they have been added to the archive since the last time the list of packages was cleared using ActionsForget new packages (f) or the command-line action forget-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.

?task(task), ~ttask

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

?term(keyword)

This term performs a full-text search for keyword in the apt package cache. When used with aptitude search, SearchLimit Display (l) in the curses front-end, or typed into a package search box in the GTK+ front-end, this term will allow aptitude to accelerate the search using a Xapian index.

?term-prefix(keyword)

This term performs a full-text search for any keyword beginning with keyword in the apt package cache. When used with aptitude search, SearchLimit Display (l) in the curses front-end, or typed into a package search box in the GTK+ front-end, this term will allow aptitude to accelerate the search using a Xapian index.

This is similar to ?term, but matches extensions of the keyword. For instance, the following search pattern will match any package indexed under the keywords hour, hourglass, hourly, and so on:

Example 2.6. Use of the ?term-prefix term

?term-prefix(hour)


?true, ~T

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

?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, ?virtual!?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.



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