apt-patterns(7)

1APT-PATTERNS(7)                       APT                      APT-PATTERNS(7)
2
3
4

NAME

6       apt-patterns - Syntax and semantics of apt search patterns
7

DESCRIPTION

9       Starting with version 2.0, APT provides support for patterns, which can
10       be used to query the apt cache for packages.
11

LOGIC PATTERNS

13       These patterns provide the basic means to combine other patterns into
14       more complex expressions, as well as ?true and ?false patterns.
15
16       ?and(PATTERN, PATTERN, ...), PATTERN PATTERN ...
17           Selects objects where all specified patterns match.
18
19       ?false, ~F
20           Selects nothing.
21
22       ?not(PATTERN), !PATTERN
23           Selects objects where PATTERN does not match.
24
25       ?or(PATTERN, PATTERN, ...), PATTERN | PATTERN | ...
26           Selects objects where at least one of the specified patterns match.
27
28       ?true, ~T
29           Selects all objects.
30
31       (PATTERN)
32           Selects the same as PATTERN, can be used to work around precedence,
33           for example, (~ramd64|~ri386)~nfoo
34

NARROWING PATTERNS

36       ?all-versions(PATTERN)
37           Selects packages where all versions match PATTERN. When matching
38           versions instead, same as PATTERN.
39
40       ?any-version(PATTERN)
41           Selects any version where the pattern matches on the version.
42
43           For example, while ?and(?version(1),?version(2)) matches a package
44           which has one version containing 1 and one version containing 2,
45           ?any-version(?and(?version(1),?version(2))) restricts the ?and to
46           act on the same version.
47
48       ?narrow(PATTERN...)
49           Selects any version matching all PATTERNs, short for
50           ?any-version(?and(PATTERN...)).
51

PACKAGE PATTERNS

53       These patterns select specific packages.
54
55       ?architecture(WILDCARD), ~rWILDCARD
56           Selects packages matching the specified architecture, which may
57           contain wildcards using any.
58
59       ?automatic, ~M
60           Selects packages that were installed automatically.
61
62       ?broken, ~b
63           Selects packages that have broken dependencies.
64
65       ?config-files, ~c
66           Selects packages that are not fully installed, but have solely
67           residual configuration files left.
68
69       ?essential, ~E
70           Selects packages that have Essential: yes set in their control
71           file.
72
73       ?exact-name(NAME)
74           Selects packages with the exact specified name.
75
76       ?garbage, ~g
77           Selects packages that can be removed automatically.
78
79       ?installed, ~i
80           Selects packages that are currently installed. Since version 2.5.4,
81           narrowing this pattern (see narrowing patterns above) makes it only
82           match installed versions (see version patterns below).
83
84       ?name(REGEX), ~nREGEX
85           Selects packages where the name matches the given regular
86           expression.
87
88       ?obsolete, ~o
89           Selects packages that no longer exist in repositories.
90
91       ?upgradable, ~U
92           Selects packages that can be upgraded (have a newer candidate).
93
94       ?virtual, ~v
95           Selects all virtual packages; that is packages without a version.
96           These exist when they are referenced somewhere in the archive, for
97           example because something depends on that name.
98

VERSION PATTERNS

100       These patterns select specific versions of a package.
101
102       ?archive(REGEX), ~AREGEX
103           Selects versions that come from the archive that matches the
104           specified regular expression. Archive, here, means the values after
105           a= in apt-cache policy.
106
107       ?codename(REGEX)
108           Selects versions that come from the codename that matches the
109           specified regular expression. Codename, here, means the values
110           after n= in apt-cache policy.
111
112       ?installed, ~i
113           Selects package versions that are currently installed. Versions
114           prior to 2.5.4 only matched at the package level, hence
115           ?any-version(?installed?version(2.0))matched even if 2.0 was not
116           installed, but another version was.
117
118       ?origin(REGEX), ~OREGEX
119           Selects versions that come from the origin that matches the
120           specified regular expression. Origin, here, means the values after
121           o= in apt-cache policy.
122
123       ?section(REGEX), ~sREGEX
124           Selects versions where the section matches the specified regular
125           expression.
126
127       ?source-package(REGEX), ~eREGEX
128           Selects versions where the source package name matches the
129           specified regular expression.
130
131       ?source-version(REGEX)
132           Selects versions where the source package version matches the
133           specified regular expression.
134
135       ?version(REGEX), ~VREGEX
136           Selects versions where the version string matches the specified
137           regular expression.
138
139       ?priority(NAME), ~pNAME
140           Selects versions where the Priority string equals the given name.
141

PACKAGE RELATIONSHIP PATTERNS

143       These patterns match specific package versions that depend/conflict
144       with some other packages.
145
146       ?depends(PATTERN), ~DPATTERN, ?pre-depends(PATTERN),
147       ~DPre-Depends:PATTERN, ?suggests(PATTERN), ~DSuggests:PATTERN,
148       ?conflicts(PATTERN), ~DConflicts:PATTERN, ?replaces(PATTERN),
149       ~DReplaces:PATTERN, ?obsoletes(PATTERN), ~DObsoletes:PATTERN,
150       ?breaks(PATTERN), ~DBreaks:PATTERN, ?enhances(PATTERN),
151       ~DEnhances:PATTERN
152           Selects versions depending/pre-depending/suggesting/conflicting/etc
153           on/with/ packages matching PATTERN.
154
155       ?reverse-depType(PATTERN), ~RDepType:PATTERN
156           Opposite of ?depends and friends - selects all packages that have
157           reverse-dependencies (versions) matching PATTERN.
158
159           depType is one of the dependency types such as depends, so that we
160           don't have to repeat the entire list from the first paragraph here.
161

EXAMPLES

163       apt remove ?garbage
164           Remove all packages that are automatically installed and no longer
165           needed - same as apt autoremove
166
167       apt purge ?config-files
168           Purge all packages that only have configuration files left
169
170       apt list '~i !~M (~slibs|~sperl|~spython)'
171           List all manually-installed packages in sections matching libs,
172           perl, or python.
173

MIGRATING FROM APTITUDE

175       Patterns in apt are heavily inspired by patterns in aptitude, but with
176       some tweaks:
177
178       •   Syntax is uniform: If there is an opening parenthesis after a term,
179           it is always assumed to be the beginning of an argument list.
180
181           In aptitude, a syntactic form "?foo(bar)" could mean
182           "?and(?foo,bar)" if foo does not take an argument. In APT, this
183           will cause an error.
184
185       •   Not all patterns are supported.
186
187       •   Some additional patterns are available, for example, for finding
188           gstreamer codecs.
189
190       •   Escaping terms with ~ is not supported.
191
192       •   A trailing comma is allowed in argument lists
193
194       •   ?narrow accepts infinite arguments
195
196       •   foo cannot be used as a shortform for ?name(foo), as this can cause
197           typos to go unnoticed: Consider ?and(...,~poptional): this requires
198           the package to have required priority, but if you do not type the
199           ~, it would require the package name to contain poptional.
200
201       •   Dependency types for ~D and related operators need to be specified
202           in the canonical case.
203

BUGS

208       APT bug page[1]. If you wish to report a bug in APT, please see
209       /usr/share/doc/debian/bug-reporting.txt or the reportbug(1) command.
210

AUTHOR

212       APT was written by the APT team <apt@packages.debian.org>.
213

AUTHORS

215       Jason Gunthorpe
216
217       APT team
218

NOTES

220        1. APT bug page
221           http://bugs.debian.org/src:apt
222
223
224
225APT 2.7.6                       13 January 2023                APT-PATTERNS(7)