pacman

The pacman package manager is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use build system. The goal of pacman is to make it possible to easily manage packages, whether they are from the official repositories or the user's own builds.

Pacman keeps the system up-to-date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.

Pacman is written in the C programming language and uses the bsdtar(1) tar format for packaging.

Tip: The pacman package contains tools such as makepkg and vercmp(8). Other useful tools such as pactree and checkupdates are found in pacman-contrib (formerly part of pacman). Run pacman -Ql pacman pacman-contrib | grep -E 'bin/.+' to see the full list.

Usage

What follows is just a small sample of the operations that pacman can perform. To read more examples, refer to pacman(8).

Tip: For those who have used other Linux distributions before, there is a helpful Pacman Rosetta article.

Installing packages

A package is an archive containing:

all of the (compiled) files of an application
metadata about the application, such as application name, version, dependencies, etc.
installation files and directives for pacman
(optionally) extra files to make your life easier, such as a start/stop script

Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:

easily updatable: pacman will update existing packages as soon as updates are available
dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs
clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.

Note:

Packages often have optional dependencies which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, pacman will list a package's optional dependencies, but they will not be found in pacman.log. Use the #Querying package databases command to view the optional dependencies of a package.
When installing a package which you require only as a (optional) dependency of some other package (i.e. not required by you explicitly), it is recommended to use the --asdeps option. For details, see the #Installation reason section.

Warning: When installing packages in Arch, avoid refreshing the package list without upgrading the system (for example, when a package is no longer found in the official repositories). In practice, do not run pacman -Sy package_name instead of pacman -Syu package_name, as this could lead to dependency issues. See System maintenance#Partial upgrades are unsupported and BBS#89328.

Installing specific packages

To install a single package or list of packages, including dependencies, issue the following command:

# pacman -S package_name1 package_name2 ...

To install a list of packages with regex (see this forum thread):

# pacman -S $(pacman -Ssq package_regex)

Sometimes there are multiple versions of a package in different repositories (e.g. extra and testing). To install the version from the extra repository in this example, the repository needs to be defined in front of the package name:

# pacman -S extra/package_name

To install a number of packages sharing similar patterns in their names, one can use curly brace expansion. For example:

# pacman -S plasma-{desktop,mediacenter,nm}

This can be expanded to however many levels needed:

# pacman -S plasma-{workspace{,-wallpapers},pa}

Virtual packages

A virtual package is a special package which does not exist by itself, but is provided by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have installed a package providing the virtual package.

Tip: When there are multiple candidates, the list of choices presented will sort first by repositories in the order they appear in pacman.conf, then alphabetically when multiple results exist from the same repository.

Installing package groups

Some packages belong to a group of packages that can all be installed simultaneously. For example, issuing the command:

# pacman -S gnome

will prompt you to select the packages from the gnome group that you wish to install.

Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:

Enter a selection (default=all): 1-10 15

which will select packages 1 through 10 and 15 for installation, or:

Enter a selection (default=all): ^5-8 ^2

which will select all packages except 5 through 8 and 2 for installation.

To see what packages belong to the gnome group, run:

# pacman -Sg gnome

Also visit https://archlinux.org/groups/ to see what package groups are available.

Note: If a package in the list is already installed on the system, it will be reinstalled even if it is already up-to-date. This behavior can be overridden with the --needed option.

Removing packages

To remove a single package, leaving all of its dependencies installed:

# pacman -R package_name

To remove a package and its dependencies which are not required by any other installed package:

# pacman -Rs package_name

Warning: When removing a group, such as gnome, this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.

The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:

# pacman -Rsu package_name

To remove a package, its dependencies and all the packages that depend on the target package:

Warning: This operation is recursive, and must be used with care since it can remove many potentially needed packages.

# pacman -Rsc package_name

To remove a package, which is required by another package, without removing the dependent package:

Warning: The following operation can break a system and should be avoided. See System maintenance#Avoid certain pacman commands.

# pacman -Rdd package_name

Pacman saves important configuration files when removing certain applications and names them with the extension: .pacsave. To prevent the creation of these backup files use the -n option:

# pacman -Rn package_name

Note: Pacman will not remove configurations that the application itself creates (for example "dotfiles" in the home directory).

Upgrading packages

Warning:

Users are expected to follow the guidance in the System maintenance#Upgrading the system section to upgrade their systems regularly and not blindly run the following command.
Arch only supports full system upgrades. See System maintenance#Partial upgrades are unsupported and #Installing packages for details.

Pacman can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases and updates the system's packages, excluding "local" packages that are not in the configured repositories:

# pacman -Syu

Querying package databases

Pacman queries the local package database with the -Q flag, the sync database with the -S flag and the files database with the -F flag. See pacman -Q --help, pacman -S --help and pacman -F --help for the respective suboptions of each flag.

Pacman can search for packages in the database, searching both in packages' names and descriptions:

$ pacman -Ss string1 string2 ...

Sometimes, -s's builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:

$ pacman -Ss '^vim-'

To search for already installed packages:

$ pacman -Qs string1 string2 ...

To search for package file names in remote packages:

$ pacman -F string1 string2 ...

To display extensive information about a given package:

$ pacman -Si package_name

For locally installed packages:

$ pacman -Qi package_name

Passing two -i flags will also display the list of backup files and their modification states:

$ pacman -Qii package_name

To retrieve a list of the files installed by a package:

$ pacman -Ql package_name

To retrieve a list of the files installed by a remote package:

$ pacman -Fl package_name

To verify the presence of the files installed by a package:

$ pacman -Qk package_name

Passing the k flag twice will perform a more thorough check.

To query the database to know which package a file in the file system belongs to:

$ pacman -Qo /path/to/file_name

To query the database to know which remote package a file belongs to:

$ pacman -F /path/to/file_name

To list all packages no longer required as dependencies (orphans):

$ pacman -Qdt

To list all packages explicitly installed and not required as dependencies:

$ pacman -Qet

See pacman/Tips and tricks for more examples.

Pactree

Note: pactree(8) is not part of the pacman package anymore. Instead it can be found in pacman-contrib.

To view the dependency tree of a package:

$ pactree package_name

To view the dependant tree of a package, pass the reverse flag -r to pactree, or use whoneeds from pkgtools^AUR.

Database structure

The pacman databases are normally located at /var/lib/pacman/sync. For each repository specified in /etc/pacman.conf, there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the which package:

$ tree which-2.21-5

which-2.21-5
|-- desc

The desc file contains meta data such as the package description, dependencies, file size and MD5 hash.

Cleaning the package cache

Pacman stores its downloaded packages in /var/cache/pacman/pkg/ and does not remove the old or uninstalled versions automatically. This has some advantages:

It allows to downgrade a package without the need to retrieve the previous version through other means, such as the Arch Linux Archive.
A package that has been uninstalled can easily be reinstalled directly from the cache directory, not requiring a new download from the repository.

However, it is necessary to deliberately clean up the cache periodically to prevent the directory to grow indefinitely in size.

The paccache(8) script, provided within the pacman-contrib package, deletes all cached versions of installed and uninstalled packages, except for the most recent three, by default:

# paccache -r

Enable and start paccache.timer to discard unused packages weekly.

Tip: You can create a hook to run this automatically after every pacman transaction, install pacman-cleanup-hook^AUR and see other examples

You can also define how many recent versions you want to keep. To retain only one past version use:

# paccache -rk1

Add the -u/--uninstalled switch to limit the action of paccache to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:

# paccache -ruk0

See paccache -h for more options.

Pacman also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file /etc/pacman.conf. However pacman does not offer the possibility to keep a number of past versions and is therefore more aggressive than paccache default options.

To remove all the cached packages that are not currently installed, and the unused sync database, execute:

# pacman -Sc

To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache directory:

# pacman -Scc

Warning: One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.

pkgcacheclean^AUR and pacleaner^AUR are two further alternatives to clean the cache.

Additional commands

Download a package without installing it:

# pacman -Sw package_name

Install a 'local' package that is not from a remote repository (e.g. the package is from the AUR):

# pacman -U /path/to/package/package_name-version.pkg.tar.zst

To keep a copy of the local package in pacman's cache, use:

# pacman -U file:///path/to/package/package_name-version.pkg.tar.zst

Install a 'remote' package (not from a repository stated in pacman's configuration files):

# pacman -U http://www.example.com/repo/example.pkg.tar.zst

To inhibit the -S, -U and -R actions, -p can be used.

Pacman always lists packages to be installed or removed and asks for permission before it takes action.

Installation reason

The pacman database organizes installed packages into two groups, according to installation reason:

explicitly-installed: packages that were literally passed to a generic pacman -S or -U command;
dependencies: packages that, despite never (in general) having been passed to a pacman installation command, were implicitly installed because they were required by packages explicitly installed.

When installing a package, it is possible to force its installation reason to dependency with:

# pacman -S --asdeps package_name

The command is normally used because explicitly-installed packages may offer optional packages, usually for non-essential features for which the user has discretion.

Tip: Installing optional dependencies with --asdeps will ensure that, if you remove orphans, pacman will also remove optional packages set this way.

When reinstalling a package, though, the current installation reason is preserved by default.

The list of explicitly-installed packages can be shown with pacman -Qe, while the complementary list of dependencies can be shown with pacman -Qd.

To change the installation reason of an already installed package, execute:

# pacman -D --asdeps package_name

Use --asexplicit to do the opposite operation.

Note: Using --asdeps and --asexplicit options when upgrading, such as with pacman -Syu package_name --asdeps, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.

Search for a package that contains a specific file

This article or section is a candidate for merging with pacman/Tips and tricks.

Notes: Looking at #Querying package databases this section duplicates but expands what is already covered there. Either this should be moved inside the previous section or merged as a pacman tip in the dedicated article, which is already linked (Discuss in Talk:Pacman)

Sync the files database:

# pacman -Fy

Search for a package containing a file, e.g.:

$ pacman -F pacman

core/pacman 5.2.1-1 (base base-devel) [installed]
    usr/bin/pacman
    usr/share/bash-completion/completions/pacman
extra/xscreensaver 5.43-1
    usr/lib/xscreensaver/pacman