pacman

ro:Pacman zh-CN:Pacman zh-TW: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 .pkg.tar.xz package format.

Tip: The pacman package contains other useful tools such as makepkg, pactree, vercmp, and checkupdates. Run pacman -Qlq pacman | grep bin to see the full list.

1 Usage
2 Configuration
3 Troubleshooting
4 See also

Usage

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

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

Installing packages

Note: Packages often have a series of optdepends that, while not mandatory, provide additional functionality. You may refer to this information at will by #Querying package databases.

Warning: When installing packages, do not refresh the package list without upgrading the system (i.e. pacman -Sy package_name); this can lead to dependency issues. See System maintenance#Partial upgrades are unsupported and https://bbs.archlinux.org/viewtopic.php?id=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 pacman tips#Operations and Bash syntax and 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 former version, the repository needs to be defined in front:

# pacman -S extra/package_name

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://www.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

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:

# 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 folder).

Upgrading packages

It is recommended that users upgrade their system regularly. When requesting support from the community, it will usually be assumed that the system is up to date.

Before upgrading, users are expected to visit the Arch Linux home page to check the latest news, or alternatively subscribe to the RSS feed, arch-announce mailing list, or follow @archlinux on Twitter: when updates require out-of-the-ordinary user intervention (more than what can be handled simply by following the instructions given by pacman), an appropriate news post will be made. Users must equally be aware that upgrading packages can raise unexpected problems that could need immediate intervention, therefore it is discouraged to upgrade a stable system shortly before it is required for carrying out an important task: it is wise to wait instead to have enough time in order to be able to deal with possible post-upgrade issues.

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. This command can synchronize the repository databases and update the system's packages (excluding "local" packages that are not in the configured repositories):

# pacman -Syu

pacman is a powerful package management tool, but it does not attempt to handle all corner cases. Users must be vigilant and take responsibility for maintaining their own system. When performing a system update, it is essential that users read all information output by pacman and use common sense. If a user-modified configuration file needs to be upgraded for a new version of a package, a .pacnew file will be created to avoid overwriting settings modified by the user. pacman will prompt the user to merge them. These files require manual intervention from the user and it is good practice to handle them right after every package upgrade or removal. See Pacnew and Pacsave files for more information.

Tip:

Remember that pacman's output is logged in /var/log/pacman.log.
You can use a log viewer such as wat-git^AUR to search the pacman logs.

If one encounters problems that cannot be solved by these instructions, make sure to search the forum. It is likely that others have encountered the same problem and have posted instructions for solving it.

Querying package databases

pacman queries the local package database with the -Q flag; see:

$ pacman -Q --help

and queries the sync databases with the -S flag; see:

$ pacman -S --help

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

$ pacman -Ss string1 string2 ...

To search for already installed packages:

$ pacman -Qs 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

For packages not installed, use pkgfile.

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.

One can also query the database to know which package a file in the file system belongs to:

$ pacman -Qo /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

To list a dependency tree of a package:

$ pactree package_name

To list all the packages recursively depending on an installed package, use whoneeds from pkgtools:

$ whoneeds package_name

or the reverse flag to pactree:

$ pactree -r package_name

See pacman tips for more examples.

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 tar-gzipped archives containing one directory for each package, for example for the which package:

% tree which-2.20-6 
which-2.20-6
|-- depends
`-- desc

The depends file lists the packages this package depends on, while desc has a description of the package such as the file size and the 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, therefore it is necessary to deliberately clean up that folder periodically to prevent such folder to grow indefinitely in size.

The built-in option to remove all the cached packages that are not currently installed is:

# pacman -Sc

Warning:

Only do this if certain that the installed packages are stable and that a downgrade will not be necessary, since it will remove all of the old versions from the cache folder, leaving behind only the versions of the packages that are currently installed. Having older versions of packages comes in handy in case a future upgrade results in a broken system, and if they are removed from the cache the only way to retrieve them is through an alternative source of deprecated packages such as the Arch Rollback Machine.
It is also possible to completely empty the cache folder with pacman -Scc, but doing it is considered bad practice, as, in addition to the above, it also prevents from reinstalling a package directly from the cache folder in case of need, thus forcing to redownload it. You should never use it unless there is a desperate need for more disk space.

Because of the above limitations, it is recommended to use an alternative, dedicated script to have more control over which and how many packages are deleted from the cache:

The paccache command, provided by the pacman package itself, by default deletes all the cached versions of each package except for the most recent 3:
```
$ paccache -r
```
Used this way, however, paccache will not check whether a package is still installed or not, thus leaving the uninstalled packages in the cache. For removing all the cached versions of uninstalled packages, you will have to run it a second time with:
```
$ paccache -ruk0
```
See paccache -h for more options.
Alternatively, use pkgcacheclean^AUR:

# pkgcacheclean

Another option is pacleaner^AUR: to check packages to sweep except the 3 most recent:

$ pacleaner -m

To check uninstalled packages:

$ pacleaner -u

Use it as root with the --delete option to actually remove the packages. Default options such as the number of packages to keep or the path of the cache can be fine tuned in a configuration file.

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

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

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

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

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

General notes

Warning: Take care when using the --force switch because it can cause major problems if used improperly. It is highly recommended to only use this option when the Arch news instructs the user to do so.

pacman always lists packages to be installed or removed and asks for permission before it takes action. To inhibit the -S, -U and -R actions, -p can be used.

Configuration

pacman's settings are located in /etc/pacman.conf. This is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in man pacman.conf.

General options

General options are in the [options] section. Read the man page or look in the default pacman.conf for information on what can be done here.

Skip package from being upgraded

To have a specific package skipped when upgrading the system, specify it as such:

IgnorePkg=linux

For multiple packages use a space-separated list, or use additional IgnorePkg lines. Also, glob patterns can be used. If you want to skip packages just once, you can also use the --ignore option on the command-line - this time with a comma-separated list.

It will still be possible to upgrade the ignored packages using pacman -S: in this case pacman will remind you that the packages have been included in an IgnorePkg statement.

Skip package group from being upgraded

As with packages, skipping a whole package group is also possible:

IgnoreGroup=gnome

Skip files from being installed to system

To always skip installation of specific directories list them under NoExtract. For example, to avoid installation of systemd units use this:

NoExtract=usr/lib/systemd/system/*

Maintain several configuration files

If you have several configuration files (e.g. main configuration and configuration with [testing] repository enabled) and would have to share an options between configurations you may use Include option declared in the configuration files, e.g.:

Include = /path/to/common/settings

where /path/to/common/settings file contains the same options for both configurations.

Repositories

This section defines which repositories to use, as referred to in /etc/pacman.conf. They can be stated here directly or included from another file (such as /etc/pacman.d/mirrorlist), thus making it necessary to maintain only one list. See Mirrors article for mirror configuration.

Warning: Care should be taken when using the testing repository. It is in active development and updating may cause some packages to stop working. People who use the testing repository are encouraged to subscribe to the arch-dev-public mailing list for current information.

Package security

pacman 4 supports package signatures, which add an extra layer of security to the packages. The default configuration, SigLevel = Required DatabaseOptional, enables signature verification for all the packages on a global level: this can be overridden by per-repository SigLevel lines as shown above. For more details on package signing and signature verification, take a look at pacman-key.

Troubleshooting

"Failed to commit transaction (conflicting files)" error

If you see the following error: [1]

error: could not prepare transaction
error: failed to commit transaction (conflicting files)
package: /path/to/file exists in filesystem
Errors occurred, no packages were upgraded.

Why this is happening: pacman has detected a file conflict, and by design, will not overwrite files for you. This is a design feature, not a flaw.

The problem is usually trivial to solve. A safe way is to first check if another package owns the file (pacman -Qo /path/to/file). If the file is owned by another package, file a bug report. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.

If you had installed a program manually without using pacman or a frontend, for example through make install, you have to remove it and all its files and reinstall properly using pacman. See also Pacman tips#Identify files not owned by any package.

Every installed package provides a /var/lib/pacman/local/$package-$version/files file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in file exists in filesystem errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may exceptionally run pacman -S --force $package to force pacman to overwrite these files.

Warning: Take care when using the --force switch (for example pacman -Syu --force) as it can cause major problems if used improperly. It is highly recommended to only use this option when the Arch news instructs the user to do so.

"Failed to commit transaction (invalid or corrupted package)" error

Look for .part files (partially downloaded packages) in /var/cache/pacman/pkg and remove them (often caused by usage of a custom XferCommand in pacman.conf).

# find /var/cache/pacman/pkg/ -iname "*.part" -exec rm {} \;

"Failed to init transaction (unable to lock database)" error

When pacman is about to alter the package database, for example installing a package, it creates a lock file at /var/lib/pacman/db.lck. This prevents another instance of pacman from trying to alter the package database at the same time.

If pacman is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of pacman are running then delete the lock file:

# rm /var/lib/pacman/db.lck

"Not found in sync db" error upon installing a package

Firstly, ensure the package actually exists (and watch out for typos!). If certain the package exists, your package list may be out-of-date or your repositories may be incorrectly configured. Try running pacman -Syyu to force a refresh of all package lists and upgrade.

"Target not found" error upon installing a package

Firstly, ensure the package actually exists (and watch out for typos). If certain the package exists, your package list may be out of date or your repositories may be incorrectly configured. Try running pacman -Syyu to force a refresh of all package lists and upgrade.

It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the multilib repository, but multilib is not enabled in your pacman.conf.

The same package is upgraded repeatedly

Note: pacman version 3.4 should display an error in case of duplicate entries, which should make this note obsolete.

This is due to duplicate entries in /var/lib/pacman/local/, such as two linux instances. pacman -Qi outputs the correct version, but pacman -Qu recognizes the old version and therefore will attempt to upgrade.

The solution is to delete the offending entry in /var/lib/pacman/local/.

Search for a package that contains a specific file

Install pkgfile which uses a separate database with all files and their associated packages.

pacman is broken beyond repair

The factual accuracy of this article or section is disputed.

Reason: Any broken dependency of pacman also breaks pacman, but many dependencies are not mentioned (run pactree -l pacman | sort -u | cut -f 1 -d ' ' to see them all). The info below is likely just a specific case where only two dependencies were broken. (Discuss in Talk:Pacman#)

In the case that pacman is broken beyond repair, manually download the necessary packages (openssl, libarchive, and pacman) and extract them to root. The pacman binary will be restored along with its default configuration file. Afterwards, reinstall these packages with pacman to maintain package database integrity. Additional information and an example (outdated) script that automates the process is available in this forum post.

Alternatively, you can also use an Arch live media and follow #pacman crashes during an upgrade to re-install pacman.

pacman crashes during an upgrade

In the case that pacman crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:

Boot using the Arch installation media. Preferably use a recent media so that the pacman version matches/is newer than the system.
Mount the system's root filesystem, e.g. mount /dev/sdaX /mnt as root, and check the mount has sufficient space with df -h
If the system uses default database and directory locations, you can now update the system's pacman database and upgrade it via pacman --root=/mnt --cachedir=/mnt/var/cache/pacman/pkg -Syyu as root.
After the upgrade, one way to double-check for not upgraded but still broken packages: find /mnt/usr/lib -size 0
Followed by a re-install of any still broken package via pacman --root /mnt --cachedir=/mnt/var/cache/pacman/pkg -S package.

pacman crashes the official installation media

The official installation media (ISO) before version 10.2015 are not setup to be updated itself at runtime. Running pacman -Syu from a booted install media console may crash unexpectedly any time, as soon as memory is depleted. This happens because the install media image build reports an arbitrary capacity (of 32GB) to pacman, regardless of available free memory.[2] At the same time the ISO reserves only a low static memory allotment for operations (/run/archiso/cowspace of 256MB RAM) of the live system, in order to allow installation on machines with low resources. If the machine has more RAM available, you can override the allotment by setting the cow_spacesize= kernel option for the ISO manually, e.g. cow_spacesize=2GB.

If you use the install media to update an installed system, you simply have to use the --root= option along with a --cachedir= path to point pacman to available real storage. For example, see #pacman crashes during an upgrade.

If you require an install media with persistent dataspace, the Archiso build script can be used to create one along with its boot options.

"Unable to find root device" error after rebooting

Most likely your initramfs got broken during a kernel update (improper use of pacman's --force option can be a cause). You have two options; first, try the Fallback entry:

Tip: In case you removed this entry for whatever reason, you can always press the Tab key when the bootloader menu shows up (for Syslinux) or e (for GRUB or gummiboot), rename it initramfs-linux-fallback.img and press Enter or b (depending on your bootloader) to boot with the new parameters.

Once the system starts, run this command (for the stock linux kernel) either from the console or from a terminal to rebuild the initramfs image:

# mkinitcpio -p linux

If that does not work, from a current Arch release (CD/DVD or USB stick), run:

Note: If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can chroot using the old fashion way. Obviously, there will be more typing than simply running the arch-chroot script.

# mount /dev/sdxY /mnt         # Your root partition.
# mount /dev/sdxZ /mnt/boot    # If you use a separate /boot partition.
# arch-chroot /mnt
# pacman -Syu mkinitcpio systemd linux

Note: If pacman fails with Could not resolve host, please check your internet connection.

Reinstalling the kernel (the linux package) will automatically re-generate the initramfs image with mkinitcpio -p linux. There is no need to do this separately.

Afterwards, it is recommended that you run exit, umount /mnt/{boot,} and reboot.

Note: If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command pacman -r /mnt -Syu foo bar to use pacman on your root partition.

Signature from "User <email@gmail.com>" is unknown trust, installation failed

Follow pacman-key#Resetting all the keys. Or you can try to either:

update the known keys, i.e. pacman-key --refresh-keys;
or manually upgrade archlinux-keyring package first, i.e. pacman -S archlinux-keyring.

Request on importing PGP keys

If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade archlinux-keyring (see above).

Signature from "User <email@archlinux.org>" is invalid, installation failed

When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:

error: package: signature from "User <email@archlinux.org>" is invalid
error: failed to commit transaction (invalid or corrupted package (PGP signature))
Errors occured, no packages were upgraded.

Make sure to correct the time, for example with ntpd -qg run as root, and run hwclock -w as root before subsequent installations or upgrades.

"Warning: current locale is invalid; using default "C" locale" error

As the error message says, your locale is not correctly configured. See Locale.

pacman does not honor proxy settings

Make sure that the relevant environment variables ($http_proxy, $ftp_proxy etc.) are set up. If you use pacman with sudo, you need to configure sudo to pass these environment variables to pacman.

How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency?

To reinstall all the native packages: pacman -Qnq | pacman -S - (the -S option preserves the installation reason by default).

You will then need to reinstall all the foreign packages, which can be listed with pacman -Qmq.

"Cannot open shared object file" error

It looks like previous pacman transaction removed or corrupted shared libraries needed for pacman itself.

To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the pacman cache (/var/cache/pacman/pkg/). Unpack required shared library to the filesystem. This will allow to run pacman.

Now you need to reinstall the broken package. Note that you need to use --force flag as you just unpacked system files and pacman does not know about it. pacman will correctly replace our shared library file with one from package.

That's it. Update the rest of the system.

Freeze of package downloads

Some issues have been reported regarding network problems that prevent pacman from updating/synchronizing repositories. [3] [4] When installing Arch Linux natively, these issues have been resolved by replacing the default pacman file downloader with an alternative (see Improve pacman performance for more details). When installing Arch Linux as a guest OS in VirtualBox, this issue has also been addressed by using Host interface instead of NAT in the machine properties.

Failed retrieving file 'core.db' from mirror

If you receive this error message with correct mirrors, try setting a different name server.

Contents