doc/pacman.8.txt

   1 /////
   2 vim:set ts=4 sw=4 syntax=asciidoc noet:
   3 /////
   4 pacman(8)
   5 =========
   6
   7 Name
   8 ----
   9 pacman - package manager utility
  10
  11
  12 Synopsis
  13 --------
  14 'pacman' <operation> [options] [packages]
  15
  16
  17 Description
  18 -----------
  19 Pacman is a package management utility that tracks installed packages on a Linux
  20 system. It features dependency support, package groups, install and uninstall
  21 hooks, and the ability to sync your local machine with a remote ftp server to
  22 automatically upgrade packages. Pacman packages are a zipped tar format.
  23
  24 Since version 3.0.0, pacman has been the frontend to linkman:libalpm[3], the
  25 ``Arch Linux Package Management'' library. This library allows alternative
  26 front ends to be written (for instance, a GUI front end).
  27
  28
  29 Operations
  30 ----------
  31 *-D, \--database*::
  32         Modify the package database. This options allows you to modify certain
  33         attributes of the installed packages in pacman's database. At the
  34         moment, you can only change the install reason using '\--asdeps' and
  35         '\--asexplicit' options.
  36
  37 *-Q, \--query*::
  38         Query the package database. This operation allows you to view installed
  39         packages and their files, as well as meta-information about individual
  40         packages (dependencies, conflicts, install date, build date, size). This
  41         can be run against the local package database or can be used on
  42         individual '.tar.gz' packages. In the first case, if no package names
  43         are provided in the command line, all installed packages will be
  44         queried. Additionally, various filters can be applied on the package
  45         list. See <<QO,Query Options>> below.
  46
  47 *-R, \--remove*::
  48         Remove package(s) from the system. Groups can also be specified to be
  49         removed, in which case every package in that group will be removed.
  50         Files belonging to the specified package will be deleted, and the
  51         database will be updated. Most configuration files will be saved
  52         with a `.pacsave` extension unless the '\--nosave' option is used.
  53         See <<RO,Remove Options>> below.
  54
  55 *-S, \--sync*::
  56         Synchronize packages. Packages are installed directly from the ftp
  57         servers, including all dependencies required to run the packages. For
  58         example, `pacman -S qt` will download and install qt and all the
  59         packages it depends on. If a package name exists in more than one repo, the
  60         repo can be explicitly specified to clarify the package to install:
  61         `pacman -S testing/qt`. You can also specify version requirements:
  62         `pacman -S "bash>=3.2"`. (Quotes are needed, otherwise your shell
  63         interprets ">" as redirection to file.)
  64 +
  65 In addition to packages, groups can be specified as well. For example, if
  66 gnome is a defined package group, then `pacman -S gnome` will install every
  67 package in the gnome group, as well as the dependencies of those packages.
  68 +
  69 Packages which provide other packages are also handled. For example, `pacman -S
  70 foo` will first look for a foo package. If foo is not found, packages which
  71 provide the same functionality as foo will be searched for. If any package is
  72 found, it will be installed.
  73 +
  74 You can also use `pacman -Su` to upgrade all packages that are out of date. See
  75 <<SO,Sync Options>> below. When upgrading, pacman performs version comparison
  76 to determine which packages need upgrading. This behavior operates as follows:
  77
  78   Alphanumeric:
  79     1.0a < 1.0alpha < 1.0b < 1.0beta < 1.0p < 1.0pre < 1.0rc < 1.0
  80   Numeric:
  81     1 < 1.0 < 1.1 < 1.1.1 < 1.2 < 2.0 < 3.0.0
  82 +
  83 Additionally, packages can have an 'epoch' value defined that will override any
  84 version comparison and force an upgrade.
  85
  86 *-T, \--deptest*::
  87         Check dependencies; this is useful in scripts such as makepkg to check
  88         installed packages. This operation will check each dependency specified and
  89         return a list of those which are not currently satisfied on the system.
  90         This operation accepts no other options. Example usage: `pacman -T qt
  91         "bash>=3.2"`.
  92
  93 *-U, \--upgrade*::
  94         Upgrade or add package(s) to the system and install the required
  95         dependencies from sync repos. Either a URL or file path can be
  96         specified. This is a ``remove-then-add'' process. See <<UO,Upgrade
  97         Options>> below; also see <<HCF,Handling Config Files>> for an explanation
  98         on how pacman takes care of config files.
  99
 100 *-V, \--version*::
 101         Display version and exit.
 102
 103 *-h, \--help*::
 104         Display syntax for the given operation. If no operation was supplied
 105         then the general syntax is shown.
 106
 107
 108 Options
 109 -------
 110 *-b, \--dbpath* <'path'>::
 111         Specify an alternative database location (a typical default is
 112         ``{localstatedir}/lib/pacman'').  This should not be used unless you know what you are
 113         doing. *NOTE*: if specified, this is an absolute path and the root path is
 114         not automatically prepended.
 115
 116 *-r, \--root* <'path'>::
 117         Specify an alternative installation root (default is ``/''). This should
 118         not be used as a way to install software into ``/usr/local'' instead of
 119         ``/usr''. This option is used if you want to install a package on a
 120         temporary mounted partition which is "owned" by another system.
 121         *NOTE*: if database path or logfile are not specified on either the
 122         command line or in linkman:pacman.conf[5], their default location will
 123         be inside this root path.
 124
 125 *-v, \--verbose*::
 126         Output paths such as as the Root, Conf File, DB Path, Cache Dirs, etc.
 127
 128 *\--arch* <'arch'>::
 129         Specify an alternate architecture.
 130
 131 *\--cachedir* <'dir'>::
 132         Specify an alternative package cache location (a typical default is
 133         ``{localstatedir}/cache/pacman/pkg''). Multiple cache directories can be specified,
 134         and they are tried in the order they are passed to pacman. *NOTE*: this
 135         is an absolute path, the root path is not automatically prepended.
 136
 137 *\--config* <'file'>::
 138         Specify an alternate configuration file.
 139
 140 *\--debug*::
 141         Display debug messages. When reporting bugs, this option is recommended
 142         to be used.
 143
 144 *\--logfile* <'file'>::
 145         Specify an alternate log file. This is an absolute path, regardless of
 146         the installation root setting.
 147
 148 *\--noconfirm*::
 149         Bypass any and all ``Are you sure?'' messages. It's not a good idea to do
 150         this unless you want to run pacman from a script.
 151
 152 Transaction Options (apply to '-S', '-R' and '-U')
 153 --------------------------------------------------
 154 *-d, \--nodeps*::
 155         Skips all dependency checks. Normally, pacman will always check a
 156         package's dependency fields to ensure that all dependencies are
 157         installed and there are no package conflicts in the system.
 158
 159 *-k, \--dbonly*::
 160         Adds/Removes the database entry only, leaves all files in place.
 161
 162 *\--noprogressbar*::
 163         Do not show a progress bar when downloading files. This can be useful
 164         for scripts that call pacman and capture the output.
 165
 166 *\--noscriptlet*::
 167         If an install scriptlet exists, do not execute it. Do not use this
 168         unless you know what you are doing.
 169
 170 *-p, \--print*::
 171         Only print the targets instead of performing the actual operation (sync,
 172         remove or upgrade). Use '\--print-format' to specify how targets are
 173         displayed. The default format string is "%l", which displays url with
 174         '-S', filename with '-U' and pkgname-pkgver with '-R'.
 175
 176 *\--print-format* <'format'>::
 177         Specify a printf-like format to control the output of the '\--print'
 178         operation. The possible are attributes are : %n for pkgname, %v for pkgver,
 179         %l for location, %r for repo and %s for size.
 180
 181 Upgrade Options (apply to 'S' and 'U')[[UO]]
 182 --------------------------------------------
 183 *-f, \--force*::
 184         Bypass file conflict checks and overwrite conflicting files. If the
 185         package that is about to be installed contains files that are already
 186         installed, this option will cause all those files to be overwritten.
 187         This option should be used with care, ideally not at all.
 188
 189 *\--asdeps*::
 190         Install packages non-explicitly; in other words, fake their install reason
 191         to be installed as a dependency. This is useful for makepkg and other
 192         build from source tools that need to install dependencies before building
 193         the package.
 194
 195 *\--asexplicit*::
 196         Install packages explicitly; in other words, fake their install reason to
 197         be explicitly installed. This is useful if you want to mark a dependency
 198         as explicitly installed so it will not be removed by the '\--recursive'
 199         remove operation.
 200
 201 *\--ignore* <'package'>::
 202         Directs pacman to ignore upgrades of package even if there is one
 203         available. Multiple packages can be specified by separating them
 204         with a comma.
 205
 206 *\--ignoregroup* <'group'>::
 207         Directs pacman to ignore upgrades of all packages in 'group' even if
 208         there is one available. Multiple groups can be specified by
 209         separating them with a comma.
 210
 211 Query Options[[QO]]
 212 -------------------
 213 *-c, \--changelog*::
 214         View the ChangeLog of a package. Not every package will provide one but
 215         it will be shown if available.
 216
 217 *-d, \--deps*::
 218         Restrict or filter output to packages installed as dependencies. This
 219         option can be combined with '-t' for listing real orphans- packages that
 220         were installed as dependencies but are no longer required by any
 221         installed package. ('-Qdt' is equivalent to the pacman 3.0.X '-Qe'
 222         option.)
 223
 224 *-e, \--explicit*::
 225         Restrict or filter output to packages explicitly installed. This option
 226         can be combined with '-t' to list top-level packages- those packages
 227         that were explicitly installed but are not required by any other
 228         package. ('-Qet' is equivalent to the pacman 2.9.X '-Qe' option.)
 229
 230 *-g, \--groups*::
 231         Display all packages that are members of a named group. If a name is not
 232         specified, list all grouped packages.
 233
 234 *-i, \--info*::
 235         Display information on a given package. The '-p' option can be used if
 236         querying a package file instead of the local database. Passing two
 237         '\--info' or '-i' flags will also display the list of backup files and
 238         their modification states.
 239
 240 *-k \--check*::
 241         Check that all files owned by the given package(s) are present on the
 242         system. If packages are not specified or filter flags are not provided,
 243         check all installed packages.
 244
 245 *-l, \--list*::
 246         List all files owned by a given package. Multiple packages can be
 247         specified on the command line.
 248
 249 *-m, \--foreign*::
 250         Restrict or filter output to packages that were not found in the sync
 251         database(s).  Typically these are packages that were downloaded manually
 252         and installed with '\--upgrade'.
 253
 254 *-o, \--owns* <'file'>::
 255         Search for the package that owns file. The path can be relative or
 256         absolute.
 257
 258 *-p, \--file*::
 259         Signifies that the package supplied on the command line is a file and
 260         not an entry in the database. The file will be decompressed and queried.
 261         This is useful in combination with '\--info' and '\--list'.
 262
 263 *-q, \--quiet*::
 264         Show less information for certain query operations. (This is useful when
 265         pacman's output is processed in a script.) Search will only show package
 266         names and not version, group, and description information; owns will
 267         only show package names instead of "file is owned by pkg" messages; group
 268         will only show package names and omit group names; list will only show
 269         files and omit package names; check will only show pairs of package names
 270         and missing files; a bare query will only show package names
 271         rather than names and versions.
 272
 273 *-s, \--search* <'regexp'>::
 274         This will search each locally-installed package for names or
 275         descriptions that match `regexp`. When you include multiple search
 276         terms, only packages with descriptions matching ALL of those terms will
 277         be returned.
 278
 279 *-t, \--unrequired*::
 280         Restrict or filter output to packages not required by any currently
 281         installed package.
 282
 283 *-u, \--upgrades*::
 284         Restrict or filter output to packages that are out of date on the local
 285         system. (Only package versions are used to find outdated packages,
 286         replacements are not checked here.) This option works best if the sync
 287         database is refreshed using '-Sy'.
 288
 289
 290 Remove Options[[RO]]
 291 --------------------
 292 *-c, \--cascade*::
 293         Remove all target packages, as well as all packages that depend on one
 294         or more target packages. This operation is recursive, and must be used
 295         with care since it can remove many potentially needed packages.
 296
 297 *-n, \--nosave*::
 298         Instructs pacman to ignore file backup designations. Normally, when a
 299         file is removed from the system the database is checked to see if the
 300         file should be renamed with a ``.pacsave'' extension.
 301
 302 *-s, \--recursive*::
 303         Remove each target specified including all of their dependencies, provided
 304         that (A) they are not required by other packages; and (B) they were not
 305         explicitly installed by the user. This operation is recursive and analogous
 306         to a backwards '\--sync' operation, and helps keep a clean system without
 307         orphans. If you want to omit condition (B), pass this option twice.
 308
 309 *-u, \--unneeded*::
 310         Removes the targets that are not required by any other packages.
 311         This is mostly useful when removing a group without using the '-c' option,
 312         to avoid breaking any dependencies.
 313
 314
 315 Sync Options[[SO]]
 316 ------------------
 317 *-c, \--clean*::
 318         Remove packages that are no longer installed from the cache as well as
 319         currently unused sync databases to free up disk space. When pacman
 320         downloads packages, it saves them in a cache directory. In addition,
 321         databases are saved for every sync DB you download from, and are not
 322         deleted even if they are removed from the configuration file
 323         linkman:pacman.conf[5]. Use one '\--clean' switch to only remove
 324         packages that are no longer installed; use two to remove all packages
 325         from the cache. In both cases, you will have a yes or no option to
 326         remove packages and/or unused downloaded databases.
 327 +
 328 If you use a network shared cache, see the 'CleanMethod' option in
 329 linkman:pacman.conf[5].
 330
 331 *-g, \--groups*::
 332         Display all the members for each package group specified. If no group
 333         names are provided, all groups will be listed; pass the flag twice to
 334         view all groups and their members.
 335
 336 *-i, \--info*::
 337         Display information on a given sync database package. Passing two '\--info'
 338         or '-i' flags will also display those packages in all repositories that
 339         depend on this package.
 340
 341 *-l, \--list*::
 342         List all packages in the specified repositories. Multiple repositories
 343         can be specified on the command line.
 344
 345 *-q, \--quiet*::
 346         Show less information for certain sync operations. (This is useful when
 347         pacman's output is processed in a script.) Search will only show package
 348         names and not repo, version, group, and description information; list
 349         will only show package names and omit databases and versions; group will
 350         only show package names and omit group names.
 351
 352 *-s, \--search* <'regexp'>::
 353         This will search each package in the sync databases for names or
 354         descriptions that match `regexp`. When you include multiple search
 355         terms, only packages with descriptions matching ALL of those terms will
 356         be returned.
 357
 358 *-u, \--sysupgrade*::
 359         Upgrades all packages that are out of date. Each currently-installed
 360         package will be examined and upgraded if a newer package exists. A
 361         report of all packages to upgrade will be presented and  the operation
 362         will not proceed without user confirmation. Dependencies are
 363         automatically resolved at this level and will be installed/upgraded if
 364         necessary. Pass this option twice to enable package downgrade; in this
 365         case pacman will select sync packages whose version does not match with
 366         the local version. This can be useful when the user switches from a testing
 367         repo to a stable one. Additional targets can also be specified manually, so
 368         that '-Su foo' will do a system upgrade and install/upgrade the foo package in
 369         the same operation.
 370
 371 *-w, \--downloadonly*::
 372         Retrieve all packages from the server, but do not install/upgrade
 373         anything.
 374
 375 *-y, \--refresh*::
 376         Download a fresh copy of the master package list from the server(s)
 377         defined in linkman:pacman.conf[5]. This should typically be used each time
 378         you use '\--sysupgrade' or '-u'. Passing two '\--refresh' or '-y' flags
 379         will force a refresh of all package lists even if they are thought to be up
 380         to date.
 381
 382 *\--needed*::
 383         Don't reinstall the targets that are already up-to-date.
 384
 385
 386 Handling Config Files[[HCF]]
 387 ----------------------------
 388 Pacman uses the same logic as rpm to determine action against files that are
 389 designated to be backed up. During an upgrade, 3 md5 hashes are used for each
 390 backup file to determine the required action: one for the original file
 391 installed, one for the new file that's about to be installed, and one for the
 392 actual file existing on the filesystem. After comparing these 3 hashes, the
 393 follow scenarios can result:
 394
 395 original=X, current=X, new=X::
 396         All three files are the same, so overwrites are not an issue Install the
 397         new file.
 398
 399 original=X, current=X, new=Y::
 400         The current file is the same as the original but the new one differs.
 401         Since the user did not ever modify the file, and the new one may contain
 402         improvements or bugfixes, install the new file.
 403
 404 original=X, current=Y, new=X::
 405         Both package versions contain the exact same file, but the one on the
 406         filesystem has  been  modified. Leave the current file in place.
 407
 408 original=X, current=Y, new=Y::
 409         The new file is identical to the current file. Install the new file.
 410
 411 original=X, current=Y, new=Z::
 412         All three files are different, so install the new file with a '.pacnew'
 413         extension and warn the user. The user must then manually merge any
 414         necessary changes into the original file.
 415
 416
 417 Examples
 418 --------
 419
 420 pacman -Ss ne.hack::
 421         Search for regexp "ne.hack" in package database.
 422
 423 pacman -S gpm::
 424         Download and install gpm including dependencies.
 425
 426 pacman -U /home/user/ceofhack-0.6-1-x86_64.pkg.tar.gz::
 427         Install ceofhack-0.6-1 package from a local file.
 428
 429 pacman -Syu::
 430         Update package list and upgrade all packages afterwards.
 431
 432 pacman -Syu gpm::
 433         Update package list, upgrade all packages, and then install gpm if it
 434         wasn't already installed.
 435
 436 Configuration
 437 -------------
 438 See linkman:pacman.conf[5] for more details on configuring pacman using the
 439 'pacman.conf' file.
 440
 441
 442 See Also
 443 --------
 444 linkman:pacman.conf[5], linkman:makepkg[8], linkman:libalpm[3]
 445
 446 include::footer.txt[]