2 vim:set ts=4 sw=4 syntax=asciidoc noet:
9 pacman - package manager utility
14 'pacman' <operation> [options] [targets]
18 Pacman is a package management utility that tracks installed packages on a Linux
19 system. It features dependency support, package groups, install and uninstall
20 hooks, and the ability to sync your local machine with a remote ftp server to
21 automatically upgrade packages. Pacman packages are a zipped tar format.
23 Since version 3.0.0, pacman has been the frontend to linkman:libalpm[3], the
24 ``Arch Linux Package Management'' library. This library allows alternative
25 front ends to be written (for instance, a GUI front end).
27 Invoking pacman involves specifying an operation with any potential options and
28 targets to operate on. A 'target' is usually a package name, filename, URL, or
29 a search string. Targets can be provided as command line arguments.
30 Additionally, if a single dash (-) is passed as an argument, targets will be
37 Modify the package database. This operation allows you to modify certain
38 attributes of the installed packages in pacman's database. At the
39 moment, you can only change the install reason using '\--asdeps' and
40 '\--asexplicit' options.
43 Query the package database. This operation allows you to view installed
44 packages and their files, as well as meta-information about individual
45 packages (dependencies, conflicts, install date, build date, size). This
46 can be run against the local package database or can be used on
47 individual '.tar.gz' packages. In the first case, if no package names
48 are provided in the command line, all installed packages will be
49 queried. Additionally, various filters can be applied on the package
50 list. See <<QO,Query Options>> below.
53 Remove package(s) from the system. Groups can also be specified to be
54 removed, in which case every package in that group will be removed.
55 Files belonging to the specified package will be deleted, and the
56 database will be updated. Most configuration files will be saved
57 with a '.pacsave' extension unless the '\--nosave' option is used.
58 See <<RO,Remove Options>> below.
61 Synchronize packages. Packages are installed directly from the ftp
62 servers, including all dependencies required to run the packages. For
63 example, `pacman -S qt` will download and install qt and all the
64 packages it depends on. If a package name exists in more than one repo, the
65 repo can be explicitly specified to clarify the package to install:
66 `pacman -S testing/qt`. You can also specify version requirements:
67 `pacman -S "bash>=3.2"`. (Quotes are needed, otherwise your shell
68 interprets ">" as redirection to file.)
70 In addition to packages, groups can be specified as well. For example, if
71 gnome is a defined package group, then `pacman -S gnome` will provide a
72 prompt allowing you to select which packages to install from a numbered list.
73 The package selection is specified using a space separated list of package
74 numbers. Sequential packages may be selected by specifying the first and last
75 package numbers separated by a hyphen (`-`). Excluding packages is achieved by
76 prefixing a number or range of numbers with a caret (`^`).
78 Packages that provide other packages are also handled. For example, `pacman -S
79 foo` will first look for a foo package. If foo is not found, packages that
80 provide the same functionality as foo will be searched for. If any package is
81 found, it will be installed. A selection prompt is provided if multiple packages
82 providing foo are found.
84 You can also use `pacman -Su` to upgrade all packages that are out of date. See
85 <<SO,Sync Options>> below. When upgrading, pacman performs version comparison
86 to determine which packages need upgrading. This behavior operates as follows:
89 1.0a < 1.0alpha < 1.0b < 1.0beta < 1.0p < 1.0pre < 1.0rc < 1.0
91 1 < 1.0 < 1.1 < 1.1.1 < 1.2 < 2.0 < 3.0.0
93 Additionally, version strings can have an 'epoch' value defined that will
94 overrule any version comparison (unless the epoch values are equal). This is
95 specified in an `epoch:version-rel` format. For example, `2:1.0-1` is always
96 greater than `1:3.6-1`.
99 Check dependencies; this is useful in scripts such as makepkg to check
100 installed packages. This operation will check each dependency specified and
101 return a list of dependencies that are not currently satisfied on the system.
102 This operation accepts no other options. Example usage: `pacman -T qt
106 Upgrade or add package(s) to the system and install the required
107 dependencies from sync repos. Either a URL or file path can be
108 specified. This is a ``remove-then-add'' process. See <<UO,Upgrade
109 Options>> below; also see <<HCF,Handling Config Files>> for an explanation
110 on how pacman takes care of config files.
113 Display version and exit.
116 Display syntax for the given operation. If no operation was supplied
117 then the general syntax is shown.
122 *-b, \--dbpath* <path>::
123 Specify an alternative database location (a typical default is
124 +{localstatedir}/lib/pacman+). This should not be used unless you know what you are
125 doing. *NOTE*: if specified, this is an absolute path and the root path is
126 not automatically prepended.
128 *-r, \--root* <path>::
129 Specify an alternative installation root (default is `/`). This should
130 not be used as a way to install software into `/usr/local` instead of
131 `/usr`. This option is used if you want to install a package on a
132 temporary mounted partition that is "owned" by another system.
133 *NOTE*: if database path or logfile are not specified on either the
134 command line or in linkman:pacman.conf[5], their default location will
135 be inside this root path.
138 Output paths such as as the Root, Conf File, DB Path, Cache Dirs, etc.
141 Specify an alternate architecture.
143 *\--cachedir* <dir>::
144 Specify an alternative package cache location (a typical default is
145 +{localstatedir}/cache/pacman/pkg+). Multiple cache directories can be specified,
146 and they are tried in the order they are passed to pacman. *NOTE*: this
147 is an absolute path, the root path is not automatically prepended.
150 Specify an alternate configuration file.
153 Display debug messages. When reporting bugs, this option is recommended
157 Specify a directory of files used by GnuPG to verify package signatures (a
158 typical default is +{sysconfdir}/pacman.d/gnupg+). This directory should contain
159 two files: `pubring.gpg` and `trustdb.gpg`. `pubring.gpg` holds the public keys
160 of all packagers. `trustdb.gpg` contains a so-called trust database, which
161 specifies that the keys are authentic and trusted. *NOTE*: this is an absolute
162 path, the root path is not automatically prepended.
164 *\--logfile* <file>::
165 Specify an alternate log file. This is an absolute path, regardless of
166 the installation root setting.
169 Bypass any and all ``Are you sure?'' messages. It's not a good idea to do
170 this unless you want to run pacman from a script.
172 Transaction Options (apply to '-S', '-R' and '-U')
173 --------------------------------------------------
175 Skips dependency version checks. Package names are still checked. Normally,
176 pacman will always check a package's dependency fields to ensure that all
177 dependencies are installed and there are no package conflicts in the
178 system. Specify this option twice to skip all dependency checks.
181 Adds/Removes the database entry only, leaves all files in place.
184 Do not show a progress bar when downloading files. This can be useful
185 for scripts that call pacman and capture the output.
188 If an install scriptlet exists, do not execute it. Do not use this
189 unless you know what you are doing.
192 Only print the targets instead of performing the actual operation (sync,
193 remove or upgrade). Use '\--print-format' to specify how targets are
194 displayed. The default format string is "%l", which displays URLs with
195 '-S', filenames with '-U' and pkgname-pkgver with '-R'.
197 *\--print-format* <format>::
198 Specify a printf-like format to control the output of the '\--print'
199 operation. The possible attributes are: %n for pkgname, %v for pkgver,
200 %l for location, %r for repo and %s for size.
202 Upgrade Options (apply to '-S' and '-U')[[UO]]
203 --------------------------------------------
205 Bypass file conflict checks and overwrite conflicting files. If the
206 package that is about to be installed contains files that are already
207 installed, this option will cause all those files to be overwritten.
208 This option should be used with care, ideally not at all.
211 Install packages non-explicitly; in other words, fake their install reason
212 to be installed as a dependency. This is useful for makepkg and other
213 build from source tools that need to install dependencies before building
217 Install packages explicitly; in other words, fake their install reason to
218 be explicitly installed. This is useful if you want to mark a dependency
219 as explicitly installed so it will not be removed by the '\--recursive'
222 *\--ignore* <package>::
223 Directs pacman to ignore upgrades of package even if there is one
224 available. Multiple packages can be specified by separating them
227 *\--ignoregroup* <group>::
228 Directs pacman to ignore upgrades of all packages in 'group' even if
229 there is one available. Multiple groups can be specified by
230 separating them with a comma.
235 View the ChangeLog of a package if it exists.
238 Restrict or filter output to packages installed as dependencies. This
239 option can be combined with '-t' for listing real orphans - packages that
240 were installed as dependencies but are no longer required by any
244 Restrict or filter output to explicitly installed packages. This option
245 can be combined with '-t' to list explicitly installed packages that
246 are not required by any other package.
249 Display all packages that are members of a named group. If a name is not
250 specified, list all grouped packages.
253 Display information on a given package. The '-p' option can be used if
254 querying a package file instead of the local database. Passing two
255 '\--info' or '-i' flags will also display the list of backup files and
256 their modification states.
259 Check that all files owned by the given package(s) are present on the
260 system. If packages are not specified or filter flags are not provided,
261 check all installed packages.
264 List all files owned by a given package. Multiple packages can be
265 specified on the command line.
268 Restrict or filter output to packages that were not found in the sync
269 database(s). Typically these are packages that were downloaded manually
270 and installed with '\--upgrade'.
272 *-o, \--owns* <file>::
273 Search for packages that own the specified file(s). The path can be
274 relative or absolute and one or more files can be specified.
277 Signifies that the package supplied on the command line is a file and
278 not an entry in the database. The file will be decompressed and queried.
279 This is useful in combination with '\--info' and '\--list'.
282 Show less information for certain query operations. (This is useful when
283 pacman's output is processed in a script.) Search will only show package
284 names and not version, group, and description information; owns will
285 only show package names instead of "file is owned by pkg" messages; group
286 will only show package names and omit group names; list will only show
287 files and omit package names; check will only show pairs of package names
288 and missing files; a bare query will only show package names
289 rather than names and versions.
291 *-s, \--search* <regexp>::
292 Search each locally-installed package for names or descriptions that
293 match `regexp`. When including multiple search terms, only packages
294 with descriptions matching ALL of those terms are returned.
296 *-t, \--unrequired*::
297 Restrict or filter output to packages not required by any currently
301 Restrict or filter output to packages that are out of date on the local
302 system. (Only package versions are used to find outdated packages,
303 replacements are not checked here.) This option works best if the sync
304 database is refreshed using '-Sy'.
310 Remove all target packages, as well as all packages that depend on one
311 or more target packages. This operation is recursive, and must be used
312 with care since it can remove many potentially needed packages.
315 Instructs pacman to ignore file backup designations. Normally, when a
316 file is removed from the system the database is checked to see if the
317 file should be renamed with a '.pacsave' extension.
320 Remove each target specified including all of their dependencies, provided
321 that (A) they are not required by other packages; and (B) they were not
322 explicitly installed by the user. This operation is recursive and analogous
323 to a backwards '\--sync' operation, and helps keep a clean system without
324 orphans. If you want to omit condition (B), pass this option twice.
327 Removes targets that are not required by any other packages.
328 This is mostly useful when removing a group without using the '-c' option,
329 to avoid breaking any dependencies.
335 Remove packages that are no longer installed from the cache as well as
336 currently unused sync databases to free up disk space. When pacman
337 downloads packages, it saves them in a cache directory. In addition,
338 databases are saved for every sync DB you download from, and are not
339 deleted even if they are removed from the configuration file
340 linkman:pacman.conf[5]. Use one '\--clean' switch to only remove
341 packages that are no longer installed; use two to remove all packages
342 from the cache. In both cases, you will have a yes or no option to
343 remove packages and/or unused downloaded databases.
345 If you use a network shared cache, see the 'CleanMethod' option in
346 linkman:pacman.conf[5].
349 Display all the members for each package group specified. If no group
350 names are provided, all groups will be listed; pass the flag twice to
351 view all groups and their members.
354 Display information on a given sync database package. Passing two '\--info'
355 or '-i' flags will also display those packages in all repositories that
356 depend on this package.
359 List all packages in the specified repositories. Multiple repositories
360 can be specified on the command line.
363 Show less information for certain sync operations. (This is useful when
364 pacman's output is processed in a script.) Search will only show package
365 names and not repo, version, group, and description information; list
366 will only show package names and omit databases and versions; group will
367 only show package names and omit group names.
369 *-s, \--search* <regexp>::
370 This will search each package in the sync databases for names or
371 descriptions that match `regexp`. When you include multiple search
372 terms, only packages with descriptions matching ALL of those terms will
375 *-u, \--sysupgrade*::
376 Upgrades all packages that are out of date. Each currently-installed
377 package will be examined and upgraded if a newer package exists. A
378 report of all packages to upgrade will be presented and the operation
379 will not proceed without user confirmation. Dependencies are
380 automatically resolved at this level and will be installed/upgraded if
383 Pass this option twice to enable package downgrade; in this case pacman will
384 select sync packages whose version does not match with the local version. This
385 can be useful when the user switches from a testing repo to a stable one.
387 Additional targets can also be specified manually, so that '-Su foo' will do a
388 system upgrade and install/upgrade the foo package in the same operation.
390 *-w, \--downloadonly*::
391 Retrieve all packages from the server, but do not install/upgrade anything.
394 Download a fresh copy of the master package list from the server(s)
395 defined in linkman:pacman.conf[5]. This should typically be used each time
396 you use '\--sysupgrade' or '-u'. Passing two '\--refresh' or '-y' flags
397 will force a refresh of all package lists even if they appear to be up
401 Don't reinstall the targets that are already up to date.
404 Handling Config Files[[HCF]]
405 ----------------------------
406 Pacman uses the same logic as rpm to determine action against files that are
407 designated to be backed up. During an upgrade, 3 md5 hashes are used for each
408 backup file to determine the required action: one for the original file
409 installed, one for the new file that's about to be installed, and one for the
410 actual file existing on the filesystem. After comparing these 3 hashes, the
411 follow scenarios can result:
413 original=X, current=X, new=X::
414 All three files are the same, so overwrites are not an issue. Install the
417 original=X, current=X, new=Y::
418 The current file is the same as the original but the new one differs.
419 Since the user did not ever modify the file, and the new one may contain
420 improvements or bugfixes, install the new file.
422 original=X, current=Y, new=X::
423 Both package versions contain the exact same file, but the one on the
424 filesystem has been modified. Leave the current file in place.
426 original=X, current=Y, new=Y::
427 The new file is identical to the current file. Install the new file.
429 original=X, current=Y, new=Z::
430 All three files are different, so install the new file with a '.pacnew'
431 extension and warn the user. The user must then manually merge any
432 necessary changes into the original file.
439 Search for regexp "ne.hack" in package database.
442 Download and install gpm including dependencies.
444 pacman -U /home/user/ceofhack-0.6-1-x86_64.pkg.tar.gz::
445 Install ceofhack-0.6-1 package from a local file.
448 Update package list and upgrade all packages afterwards.
451 Update package list, upgrade all packages, and then install gpm if it
452 wasn't already installed.
456 See linkman:pacman.conf[5] for more details on configuring pacman using the
462 linkman:pacman.conf[5], linkman:makepkg[8], linkman:libalpm[3]
464 include::footer.txt[]