The pkg_add command is used to install packages
created with the
pkg_create(1)
command. Packages containing pre-compiled applications from the
/usr/ports tree can be found on the
OpenBSD FTP site or on the official
OpenBSD CD.

Note:
System distribution files, e.g., base58.tgz, comp58.tgz, are
not packages and may not be installed using
pkg_add.

pkg_add can be used to install new packages, to
replace existing packages with other flavors (option
-r) or to update packages to newer versions
(option -u).

In a hurry, a new package can be installed using
‘pkg_add-Upackage’, which updates dependencies
and then installs the new package.

pkg_add relies on the file system information being
consistent. In case of a system crash,
/var/db/pkg may become corrupted. Use
pkg_check(8) to
repair things.

If a package is digitally signed:

pkg_add checks that its
signature is valid and that the compressed package data matches the
signature.

pkg_add verifies that the
signature was emitted by a valid signing key, as stored in
/etc/signify/*-pkg.pub

pkg_add verifies that each
file matches its sha256 checksum right after extraction, before doing
anything with it.

pkg_add verifies that any
dangerous mode or owner is registered in the packing-list.

By default, pkg_add enforces signed packages,
except if they come from a trusted source
(TRUSTED_PKG_PATH) or if
-Dunsigned is
specified.

In normal mode, the package names given on the command lines are names of new
packages that pkg_add should install, without
ever deinstalling existing packages.

In replacement mode, the package names given on the command lines are names of
new packages that pkg_add should install,
possibly replacing existing installed packages.

In update mode, the package names given on the command lines are names of
installed packages, and pkg_add should figure out
newer package names for these, then replace the old packages with the new.

Each package name may be specified as a filename (which normally consists of the
package name itself plus the “.tgz” suffix) or a URL referring
to FTP, HTTP, HTTPS, or SCP locations. If the given package names are not
found in the current working directory, pkg_add
will search for them in each directory (local or remote) named by the
TRUSTED_PKG_PATH environment variable, then
the PKG_PATH environment variable. If
neither TRUSTED_PKG_PATH nor
PKG_PATH are defined,
pkg_add will build its path based on the contents
of
installurl(5).
Specifying ‘-’ as a package name causes
pkg_add to read from the standard input.

pkg_add also understands ‘stems’,
that is, package names without any version specification. For instance, with
‘pkg_addkdelibs’,
pkg_add will look in the current directory (or
the PKG_PATH) for a
kdelibs package.

pkg_add may ask questions in interactive mode, or
error out otherwise. Interactive mode is the default on a tty, see options
-I/i.

For instance ‘pkg_addscreen’ is ambiguous as it matches
screen-4.03p6 and
screen-4.03p6-shm.

To avoid ambiguities, pkg_add supports
‘stems with flavors’, that is, a stem separated from flavors
with a double dash. For instance, the previous ambiguity could be resolved by
using ‘pkg_addscreen--’ (matches only the empty
flavor) or ‘pkg_addscreen--shm’ (matches only the shm
flavor).

There is also an ambiguity related to ports with multiple branches. For instance
‘pkg_addpython’ is ambiguous, as there are
several versions of python in the ports tree. So is
‘pkg_addpostfix’. The special form
‘pkgname%branch’
can be used to restrict matches to a branch matching the
pkgpath(7).

The above ambiguities can be resolved using
‘pkg_addpostfix%stable’
and ‘pkg_addpython%3.4’,
respectively.

All paths recognize special sequences ‘%a’, ‘%m’,
‘%c’, ‘%v’, which will be expanded to
‘package architecture’, ‘OS version or snapshots’,
‘full mirror path’ and ‘OS version’ respectively.

The sequences ‘%c’ and ‘%m’ are slightly more
magical. One can force them to expand to ‘snapshots’ on a
release kernel by using -Dsnap. Otherwise, on a ‘-stable’
system, they will expand ‘%c/packages’ into two directories:
<VERSION>/packages-stable and
<VERSION>/packages.

If the environment variable PKG_CACHE is set
to a directory name, every package retrieved from a distant location will also
be copied here.

Some packages may depend on other packages. When resolving dependencies
pkg_add will first look at already installed
packages, then match dependencies with the list of packages left to install,
then ask the user's opinion in interactive mode, then install default packages
that satisfy the dependencies.

Warning: Since the
pkg_add command may execute scripts or programs
contained within a package file, your system may be susceptible to
“trojan horses” or other subtle attacks from miscreants who
create dangerous packages. Be sure the specified package(s) are from trusted
sources.

Force installation of the package.
name is a keyword that states what
failsafe should be waived. Recognized keywords include:

allversions

Do not trim older p* variants of packages for
updates.

arch

Architecture recorded in package may not match.

checksum

Verify checksums before deleting or tying old
files.

dontmerge

By default, if dependencies are too strict,
pkg_add will merge updates together to
make sure everything stays in sync.
-Ddontmerge
disables that behavior.

donttie

By default, pkg_add will
try to find new files in old packages by comparing the stored sha256,
and tie the entries together to avoid extracting files needlessly.
-Ddonttie
disables that behavior.

downgrade

Don't filter out package versions older than what's
currently installed.

installed

In update mode, reinstall an existing package with the
same update signature.

libdepends

Library specifications may not be fulfilled.

nonroot

Install even if not running as root.

paranoid

Very safe update: don't run any @exec/@unexec. This may
break some packages that will need manual intervention.

repair

Attempt to repair installed packages with missing
registration data.

scripts

External scripts may fail.

SIGNER

List of trusted signers, separated by commas.
Corresponds to list of public keys under
/etc/signify we want to trust. Defaults
to any key matching ‘*pkg’ for packages, and any key
matching ‘*fw’ for firmware.

snap

Force ‘%c’ and ‘%m’ to
expand to ‘snapshots’, even on a release kernel.

unsigned

Allow the installation of unsigned packages without
warnings/errors (necessary for
ports(7),
automatically set by the build infrastructure).

Install a package under
localbase. By default,
localbase equals
/usr/local, and specifying it is not
necessary. However, packages can be created using a different
localbase (see
pkg_create(1)),
and those packages can only be installed by using the same
localbase. See
bsd.port.mk(5)
for a description of LOCALBASE.

Installs packages from the raw output of
pkg_info(1),
as saved in file. Generally, use with
pkg_info -m >file, to reproduce an installation
from machine to machine. With -z and
-lpkg_add will
try its best to reproduce the installation, even if the version numbers
don't quite match and even if some packages cannot be found.

Replace existing packages.
pkg_add will try to take every precaution to
make sure the replacement can proceed before removing the old package and
adding the new one, and it should also handle shared libraries correctly.
Among other things, pkg_add will refuse to
replace packages as soon as it needs to run scripts that might fail (use
-Dupdate to
force the replacement); pkg_add will also
refuse to replace packages when the dependencies don't quite match (use
-Dupdatedepends to force the
replacement).

Don't actually install packages, skip as many steps as
needed and report only the disk size changes that would happen. Similar to
-n, except it also skips fetching full
packages and stops at getting the information it needs.

Fuzzy package addition:
pkg_add should do its best to match package
names passed on the command line, even if the versions don't match and it
will proceed even if some packages can't be found.

By default, when adding packages via FTP, the
ftp(1) program operates
in “passive” mode. If you wish to use active mode instead, set
the FTPMODE environment variable to
“active”. If pkg_add consistently
fails to fetch a package from a site known to work, it may be because the site
does not support passive mode FTP correctly. This is very rare since
pkg_add will try active mode FTP if the server
refuses a passive mode connection.

pkg_add differentiates between packages specified
on the command line, and packages installed automatically because of
inter-dependencies: the first kind will be tagged as ‘installed
manually’. The -a option is used
internally by the
ports(7)
infrastructure and
dpb(1) to handle
dependencies.

It is also possible to tweak the ‘installed manually’ status of a
package after the fact. Running pkg_add on an
already installed package will tag it as ‘installed manually’,
even if it was already there as a dependency of something else, and doubling
the -a option will remove the ‘installed
manually’ tag from installed packages.

pkg_info(1) can be
used to show only manually-installed packages, and
pkg_delete(1)
can be used to remove dependencies when they are no longer needed.

pkg_add deals with ‘updatesets’
internally. An updateset is a collection of old package(s) to delete, and new
package(s) to install, as an atomic operation. Under normal circumstances, an
updateset contains at most one old package and one new package, but some
situations may require pkg_add to perform several
installations/deletions at once.

For each new package in an updateset, pkg_add
extracts the package's “packing information” (the packing-list,
description, and installation/deinstallation scripts) into a special staging
directory in /var/tmp (or
PKG_TMPDIR if set) and then runs through
the following sequence to fully extract the contents of the package:

A check is made to determine if the package is already
recorded as installed. If it is, the installation is terminated.

A check is made to determine if the package conflicts
(from @conflict directives; see
pkg_create(1))
with a package already recorded as installed. In non-replacement mode, its
installation is terminated.

For packages tagged with architecture constraints,
pkg_add verifies that the current machine
architecture agrees with the constraints.

All package dependencies (from
@depend and
@wantlib directives; see
pkg_create(1))
are read from the packing-list. If any of these dependencies are not
currently fulfilled, an attempt is made to find a package that meets them
and install it, looking first in the current updateset, then in the list
of packages to install passed to pkg_add; if
no adequate package can be found and installed, the installation is
terminated.

The packing-list is used as a guide for extracting files
from the package into their final locations.

After installation is complete, a copy of all package
files such as the packing-list, extra messages, or the description file is
made into /var/db/pkg/<pkg-name> for
subsequent possible use by
pkg_delete(1)
and
pkg_info(1).
Any package dependencies are recorded in the other packages'
/var/db/pkg/<other-pkg>/+REQUIRED_BY
file (if the environment variable
PKG_DBDIR is set, this overrides the
/var/db/pkg/ path shown above).

Finally, the staging area is deleted and the program
terminates.

Note that it is safe to interrupt pkg_add through
SIGINT,
SIGHUP, and other signals, as it will
safely record an interrupted install as
partial-<pkgname>[.n].

When replacing packages, the procedure is slightly different.

A check is made to determine if a similar package is
already installed. If so, its full update signature is computed, which
contains all the necessary dependency information along with the actual
package version. If that signature is identical to that of the new
package, no replacement is performed (unless -D installed is
specified).

A check is made to determine what old package(s) the new
package(s) should replace, using conflicts.
pkg_add will attempt to update those
packages. If they update to the new package(s), nothing needs to be done.
If they're part of the list of updatesets to install, the corresponding
updatesets will be merged. Otherwise, pkg_add
will add them to the current updateset, and rerun update to find suitable
update to those packages.

A check is made to determine whether the old packages will
be deleted without issue, and whether the new packages will install
correctly. This includes refusing to run any code (unless -D update), and
verifying that the new package still matches dependencies (unless -D
updatedepends).

Shared libraries deserve special treatment: each shared
library from the old packages that does no longer exist in the new
packages, but that is required from a wantlib of another package is kept
along in a stub package named
.libs-<pkgname>.

The new packages are extracted to the filesystem, using
temporary filenames of the form pkg.XXXXXXX
since the old packages are still there. The packing-list is amended to
record these names as @temp annotations, in cases the installation
fails.

The old packages are deleted as usual, except that some
packages may still depend on them. Note also that
@unexec-delete commands are not
executed.

The new packages are installed as usual, except that the
files are already present and only need to be renamed. Note also that
@exec-add commands are not executed.

Dependencies from the old packages are adjusted to point
to the correct new package.

To update packages in -u mode, pkg_add performs the
following steps.

Each package name is reduced to its stem, and every
package name with matching stem available through
PKG_PATH is considered as an update
candidate.

pkg_add searches for a
‘quirks’ package first, which may contain exceptions to
these rules. This special package contains global information, such as
packages that can be deleted because they're now part of base, or stem
changes.

Version matching occurs: unless -D downgrade, only
packages with newer versions will be considered as update candidates. Note
that version matching is costly, thus
PKG_PATH should point to a snapshot of
packages for a given version of OpenBSD, similar
to the organization on the FTP sites.

Candidates are then matched according to their pkgpaths
(see pkgpath(7)
and
pkg_create(1))
in order to weed out similar packages with distinct options.

The update signature of the candidate is compared to the
signature of the already installed package: identical signatures mean no
update needed.

If several candidates are left,
pkg_add will ask the user in interactive
mode, and not perform the update in non-interactive mode.

Once a suitable update candidate has been found,
pkg_add checks the package dependencies. If
necessary, it will install or update them first. Once all dependencies are
up to date, pkg_add will update the
package.

If a given package name cannot be found, the directories
named by PKG_PATH are searched. It
should contain a series of entries separated by colons. Each entry
consists of a directory name. URL schemes such as FTP, HTTP, HTTPS, or SCP
are also appropriate. The current directory may be indicated implicitly by
an empty directory name, or explicitly by a single period
(‘./’). Special sequences
‘%a’, ‘%c’, ‘%m’,
‘%v’ will be expanded.