22 KiB
| obj | arch-wiki | rev |
|---|---|---|
| application | https://wiki.archlinux.org/title/Pacman | 2024-12-19 |
Pacman
Pacman is the default Arch Linux Package Manager
Usage
Search for a package:
pacman -Ss <package>...
Update the local package base and upgrade all out-of-date packages:
pacman -Suy
Install a package:
pacman -S <package>...
Uninstall a package:
pacman -R <package>...
Uninstall a package and its depedencies, removing all new orphans:
pacman -Rcs <package>...
Get information about package:
pacman -Si <package>...
Install a package from local package file (.tar.xz):
pacman -U <file>
List explicitly installed packages:
pacman -Qe
List orphan packages (installed as dependencies and not required anymore):
pacman -Qdt
List installed packages and versions:
pacman -Q
Empty the entire pacman cache:
pacman -Scc
Read changelog of package:
pacman -Qc pkgname
File Conflicts
When pacman removes a package that has a configuration file, it normally creates a backup copy of that configuration file and appends .pacsave to the name of the file. Likewise, when pacman upgrades a package which includes a new configuration file created by the maintainer differing from the currently installed file, it saves a .pacnew file with the new configuration. pacman provides notice when these files are written.
Configuration
Pacman, using libalpm, will attempt to read pacman.conf each time it is invoked. This configuration file is divided into sections or repositories. Each section defines a package repository that pacman can use when searching for packages in --sync mode. The exception to this is the [options] section, which defines global options.
# /etc/pacman.conf
[options]
# Set the default root directory for pacman to install to.
# This option is used if you want to install a package on a temporary mounted partition which is "owned" by another system, or for a chroot install.
# NOTE: If database path or log file are not specified on either the command line or in pacman.conf(5), their default location will be inside this root path.
RootDir = /path/to/root/dir
# Overrides the default location of the toplevel database directory.
# The default is /var/lib/pacman/.
# Most users will not need to set this option.
# NOTE: if specified, this is an absolute path and the root path is not automatically prepended.
DBPath = /path/to/db/dir
# Overrides the default location of the package cache directory.
# The default is /var/cache/pacman/pkg/.
# Multiple cache directories can be specified, and they are tried in the order they are listed in the config file.
# If a file is not found in any cache directory, it will be downloaded to the first cache directory with write access.
# NOTE: this is an absolute path, the root path is not automatically prepended.
CacheDir = /path/to/cache/dir
# Add directories to search for alpm hooks in addition to the system hook directory (/usr/share/libalpm/hooks/).
# The default is /etc/pacman.d/hooks.
# Multiple directories can be specified with hooks in later directories taking precedence over hooks in earlier directories.
# NOTE: this is an absolute path, the root path is not automatically prepended. For more information on the alpm hooks, see alpm-hooks(5).
HookDir = /path/to/hook/dir
# Overrides the default location of the directory containing configuration files for GnuPG.
# The default is /etc/pacman.d/gnupg/.
# This directory should contain two files: pubring.gpg and trustdb.gpg.
# pubring.gpg holds the public keys of all packagers. trustdb.gpg contains a so-called trust database, which specifies that the keys are authentic and trusted.
# NOTE: this is an absolute path, the root path is not automatically prepended.
GPGDir = /path/to/gpg/dir
# Overrides the default location of the pacman log file.
# The default is /var/log/pacman.log.
# This is an absolute path and the root directory is not prepended.
LogFile = /path/to/log/file
# If a user tries to --remove a package that’s listed in HoldPkg, pacman will ask for confirmation before proceeding. Shell-style glob patterns are allowed.
HoldPkg = package ...
# Instructs pacman to ignore any upgrades for this package when performing a --sysupgrade. Shell-style glob patterns are allowed.
IgnorePkg = package ...
# Instructs pacman to ignore any upgrades for all packages in this group when performing a --sysupgrade. Shell-style glob patterns are allowed.
IgnoreGroup = group ...
# Include another configuration file.
# This file can include repositories or general configuration options.
# Wildcards in the specified paths will get expanded based on glob rules.
Include = /path/to/config/file
# If set, pacman will only allow installation of packages with the given architectures (e.g. i686, x86_64, etc).
# The special value auto will use the system architecture, provided via “uname -m”.
# If unset, no architecture checks are made.
# NOTE: Packages with the special architecture any can always be installed, as they are meant to be architecture independent.
Architecture = auto &| i686 &| x86_64 | ...
# If set, an external program will be used to download all remote files.
# All instances of %u will be replaced with the download URL.
# If present, instances of %o will be replaced with the local filename, plus a “.part” extension, which allows programs like wget to do file resumes properly.
XferCommand = /path/to/command %u [%o]
# All files listed with a NoUpgrade directive will never be touched during a package install/upgrade, and the new files will be installed with a .pacnew extension.
# These files refer to files in the package archive, so do not include the leading slash (the RootDir) when specifying them.
# Shell-style glob patterns are allowed. It is possible to invert matches by prepending a file with an exclamation mark.
# Inverted files will result in previously blacklisted files being whitelisted again. Subsequent matches will override previous ones.
# A leading literal exclamation mark or backslash needs to be escaped.
NoUpgrade = file ...
# All files listed with a NoExtract directive will never be extracted from a package into the filesystem.
# This can be useful when you don’t want part of a package to be installed.
# For example, if your httpd root uses an index.php, then you would not want the index.html file to be extracted from the apache package.
# These files refer to files in the package archive, so do not include the leading slash (the RootDir) when specifying them.
# Shell-style glob patterns are allowed. It is possible to invert matches by prepending a file with an exclamation mark.
# Inverted files will result in previously blacklisted files being whitelisted again. Subsequent matches will override previous ones.
# A leading literal exclamation mark or backslash needs to be escaped.
NoExtract = file ...
# If set to KeepInstalled (the default), the -Sc operation will clean packages that are no longer installed (not present in the local database).
# If set to KeepCurrent, -Sc will clean outdated packages (not present in any sync database).
# The second behavior is useful when the package cache is shared among multiple machines, where the local databases are usually different, but the sync databases in use could be the same.
# If both values are specified, packages are only cleaned if not installed locally and not present in any known sync database.
CleanMethod = KeepInstalled &| KeepCurrent
# Set the default signature verification level. For more information, see Package and Database Signature Checking below.
SigLevel = ...
# Set the signature verification level for installing packages using the "-U" operation on a local file. Uses the value from SigLevel as the default.
LocalFileSigLevel = ...
# Set the signature verification level for installing packages using the "-U" operation on a remote file URL. Uses the value from SigLevel as the default.
RemoteFileSigLevel = ...
# Log action messages through syslog().
# This will insert log entries into /var/log/messages or equivalent.
UseSyslog
# Automatically enable colors only when pacman’s output is on a tty.
Color
# Disables progress bars. This is useful for terminals which do not support escape characters.
NoProgressBar
# Performs an approximate check for adequate available disk space before installing packages.
CheckSpace
# Displays name, version and size of target packages formatted as a table for upgrade, sync and remove operations.
VerbosePkgLists
# Disable defaults for low speed limit and timeout on downloads.
# Use this if you have issues downloading files with proxy and/or security gateway.
DisableDownloadTimeout
# Specifies number of concurrent download streams.
# The value needs to be a positive integer.
# If this config option is not set then only one download stream is used (i.e. downloads happen sequentially).
ParallelDownloads = ...
# Specifies the user to switch to for downloading files.
# If this config option is not set then the downloads are done as the user running pacman.
DownloadUser = username
# Disable the default sandbox applied to the process downloading files on Linux systems.
# Useful if experiencing landlock related failures while downloading files when running a Linux kernel that does not support this feature.
DisableSandbox
Repository Sections
Each repository section defines a section name and at least one location where the packages can be found. The section name is defined by the string within square brackets (the two above are core and custom). Repository names must be unique and the name local is reserved for the database of installed packages. Locations are defined with the Server directive and follow a URL naming structure. If you want to use a local directory, you can specify the full path with a file:// prefix, as shown above.
A common way to define DB locations utilizes the Include directive. For each repository defined in the configuration file, a single Include directive can contain a file that lists the servers for that repository.
[core]
# use this server first
Server = ftp://ftp.archlinux.org/$repo/os/$arch
# next use servers as defined in the mirrorlist below
Include = {sysconfdir}/pacman.d/mirrorlist
# Include another config file.
Include = path
# A full URL to a location where the packages, and signatures (if available) for this repository can be found.
# Cache servers will be tried before any non-cache servers, will not be removed from the server pool for 404 download errors, and will not be used for database files.
CacheServer = url
# A full URL to a location where the database, packages, and signatures (if available) for this repository can be found.
Server = url
# Set the signature verification level for this repository. For more information, see Package and Database Signature Checking below.
SigLevel = ...
# Set the usage level for this repository. This option takes a list of tokens which must be at least one of the following:
# Sync : Enables refreshes for this repository.
# Search : Enables searching for this repository.
# Install : Enables installation of packages from this repository during a --sync operation.
# Upgrade : Allows this repository to be a valid source of packages when performing a --sysupgrade.
# All : Enables all of the above features for the repository. This is the default if not specified.
# Note that an enabled repository can be operated on explicitly, regardless of the Usage level set.
Usage = ...
Signature Checking
The SigLevel directive is valid in both the [options] and repository sections. If used in [options], it sets a default value for any repository that does not provide the setting.
- If set to
Never, no signature checking will take place. - If set to
Optional, signatures will be checked when present, but unsigned databases and packages will also be accepted. - If set to
Required, signatures will be required on all packages and databases.
Hooks
libalpm provides the ability to specify hooks to run before or after transactions based on the packages and/or files being modified. Hooks consist of a single [Action] section describing the action to be run and one or more [Trigger] section describing which transactions it should be run for.
Hooks are read from files located in the system hook directory /usr/share/libalpm/hooks, and additional custom directories specified in pacman.conf (the default is /etc/pacman.d/hooks). The file names are required to have the suffix .hook. Hooks are run in alphabetical order of their file name, where the ordering ignores the suffix.
Hooks may be overridden by placing a file with the same name in a higher priority hook directory. Hooks may be disabled by overriding them with a symlink to /dev/null.
Hooks must contain at least one [Trigger] section that determines which transactions will cause the hook to run. If multiple trigger sections are defined the hook will run if the transaction matches any of the triggers.
# Example: Force disks to sync to reduce the risk of data corruption
[Trigger]
# Select the type of operation to match targets against.
# May be specified multiple times.
# Installations are considered an upgrade if the package or file is already present on the system regardless of whether the new package version is actually greater than the currently installed version. For Path triggers, this is true even if the file changes ownership from one package to another.
# Operation = Install | Upgrade | Remove
Operation = Install
Operation = Upgrade
Operation = Remove
# Select whether targets are matched against transaction packages or files.
# Type = Path|Package
Type = Package
# The path or package name to match against the active transaction.
# Paths refer to the files in the package archive; the installation root should not be included in the path.
# Shell-style glob patterns are allowed. It is possible to invert matches by prepending a target with an exclamation mark. May be specified multiple times.
# Target = <path|package>
Target = *
[Action]
# An optional description that describes the action being taken by the hook for use in front-end output.
# Description = ...
# Packages that must be installed for the hook to run. May be specified multiple times.
# Depends = <package>
Depends = coreutils
# When to run the hook. Required.
# When = PreTransaction | PostTransaction
When = PostTransaction
# Command to run.
# Command arguments are split on whitespace. Values containing whitespace should be enclosed in quotes.
# Exec = <command>
Exec = /usr/bin/sync
# Causes the transaction to be aborted if the hook exits non-zero. Only applies to PreTransaction hooks.
# AbortOnFail
# Causes the list of matched trigger targets to be passed to the running hook on stdin.
# NeedsTargets
Repositories
You can create your own package repository.
A repository essentially consists of:
- the packages (
.tar.zst) and their signatures (.tar.zst.sig) - a package index (
.db.tar.gz)
Adding a repo
To use a repo, add it to your pacman.conf:
# Local Repository
[myrepo]
SigLevel = Optional TrustAll
Server = file:///path/to/myrepo
# Remote Repository
[myrepo]
SigLevel = Optional
Server = http://yourserver.com/myrepo
Package Database
To manage the package data (index) use the repo-add and repo-remove commands.
repo-add will update a package database by reading a built package file. Multiple packages to add can be specified on the command line.
If a matching .sig file is found alongside a package file, the signature will automatically be embedded into the database.
repo-remove will update a package database by removing the package name specified on the command line. Multiple packages to remove can be specified on the command line.
repo-add [options] <path-to-db> <package> [<package> ...]
repo-remove [options] <path-to-db> <packagename> [<packagename> ...]
| Option | Description |
|---|---|
-q, --quiet |
Force this program to keep quiet and run silently except for warning and error messages. |
-s, --sign |
Generate a PGP signature file using GnuPG. This will execute gpg --detach-sign on the generated database to generate a detached signature file, using the GPG agent if it is available. |
-k, --key <key> |
Specify a key to use when signing packages. Can also be specified using the GPGKEY environment variable. If not specified in either location, the default key from the keyring will be used. |
-v, --verify |
Verify the PGP signature of the database before updating the database. If the signature is invalid, an error is produced and the update does not proceed. |
--nocolor |
Remove color from repo-add and repo-remove output. |
repo-add ONLY OPTIONS: |
- |
-n, --new |
Only add packages that are not already in the database. Warnings will be printed upon detection of existing packages, but they will not be re-added. |
-R, --remove |
Remove old package files from the disk when updating their entry in the database. |
--include-sigs |
Include package PGP signatures in the repository database (if available) |
Package Signing
To determine if packages are authentic, pacman uses OpenPGP keys in a web of trust model. Each user also has a unique OpenPGP key, which is generated when you configure pacman-key.
Examples of webs of trust:
- Custom packages: Packages made and signed with a local key.
- Unofficial packages: Packages made and signed by a developer. Then, a local key was used to sign the developer's key.
- Official packages: Packages made and signed by a developer. The developer's key was signed by the Arch Linux master keys. You used your key to sign the master keys, and you trust them to vouch for developers.
Setup
The SigLevel option in /etc/pacman.conf determines the level of trust required to install a package with pacman -S. One can set signature checking globally, or per repository. If SigLevel is set globally in the [options] section, all packages installed with pacman -S will require signing. With the LocalFileSigLevel setting from the default pacman.conf, any packages you build, and install with pacman -U, will not need to be signed using makepkg.
For remote packages, the default configuration will only support the installation of packages signed by trusted keys:
# /etc/pacman.conf
SigLevel = Required DatabaseOptional TrustedOnly
To initialize the pacman keyring run:
pacman-key --init
Keyring Management
Verifying the master keys
The initial setup of keys is achieved using:
pacman-key --populate
OpenPGP keys are too large (2048 bits or more) for humans to work with, so they are usually hashed to create a 40-hex-digit fingerprint which can be used to check by hand that two keys are the same. The last eight digits of the fingerprint serve as a name for the key known as the '(short) key ID' (the last sixteen digits of the fingerprint would be the 'long key ID').
Adding developer keys
The official Developers' and Package Maintainers' keys are signed by the master keys, so you do not need to use pacman-key to sign them yourself. Whenever pacman encounters a key it does not recognize, it will prompt you to download it from a keyserver configured in /etc/pacman.d/gnupg/gpg.conf (or by using the --keyserver option on the command line).
Once you have downloaded a developer key, you will not have to download it again, and it can be used to verify any other packages signed by that developer.
Note
: The
archlinux-keyringpackage, which is a dependency of base, contains the latest keys. However keys can also be updated manually usingpacman-key --refresh-keys(as root). While doing--refresh-keys, your local key will also be looked up on the remote keyserver, and you will receive a message about it not being found. This is nothing to be concerned about.
Adding unofficial keys
This method can be utilized to add a key to the pacman keyring, or to enable signed unofficial user repositories.
First, get the key ID (keyid) from its owner. Then add it to the keyring using one of the two methods:
If the key is found on a keyserver, import it with:
pacman-key --recv-keys keyid
If otherwise a link to a keyfile is provided, download it and then run:
pacman-key --add /path/to/downloaded/keyfile
It is recommended to verify the fingerprint, as with any master key or any other key you are going to sign:
pacman-key --finger keyid
Finally, you must locally sign the imported key:
pacman-key --lsign-key keyid
You now trust this key to sign packages.