— install or update software
[-P type] pkg-name
command is used to install packages created with
containing pre-compiled applications from the /usr/ports
tree can be found on the OpenBSD
FTP site or on the
distribution files, e.g., base58.tgz, comp58.tgz, are not
packages and may not be installed using 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
’, which updates dependencies and then
installs the new package
Details of packing-list internals are documented in
installations and updates by default.
relies on the file system information being
consistent. In case of a system crash, /var/db/pkg
become corrupted. Use pkg_check(8)
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
- pkg_add verifies that each file
matches its sha256 checksum right after extraction, before doing anything
- 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 (
) or if
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
environment variable, then the
environment variable. If neither
are defined, pkg_add
will use the path in
’ as a package name causes
to read from the standard input.
also understands ‘stems’, that is, package
names without any version specification. For instance, with
will look in the current directory (or the
) for a kdelibs
may ask questions in interactive mode, or error out
otherwise. Interactive mode is the default on a tty, see options
For instance ‘pkg_add
’ is ambiguous as it matches
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
(matches only the empty flavor) or ‘pkg_add
’ (matches only the shm flavor).
There is also an ambiguity related to ports with multiple branches. For instance
ambiguous, as there are several versions of python in the ports tree. So is
be used to restrict matches to a branch matching the
The above ambiguities can be resolved using ‘pkg_add
All paths recognize special sequences ‘%a’, ‘%c’,
The following examples are valid:
pkg_add -v http://ftp.openbsd.org/%m/rsync--
pkg_add -v http://ftp.openbsd.org/%m/m4
pkg_add -v scp://login@host/usr/ports/packages/%a/all/tcl%8.5
If the environment variable
is set to a
directory name, every package retrieved from a distant location will also be
Some packages may depend on other packages. When resolving dependencies
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
Since the pkg_add
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.
The options are as follows:
- Assume arch as current machine
architecture for any package tests.
- Automated package installation; do not record packages as
- Force already installed packages to be tagged as installed
- Set pkg-destdir as the prefix to
prepend to any object extracted from the package.
- While replacing packages, delete extra configuration file
in the old package, mentioned as
in the packing-list.
- Force installation of the package.
name is a keyword that states what failsafe should
be waived. Recognized keywords include:
- Do not trim older p* variants of packages for
- Architecture recorded in package may not match.
- By default, if dependencies are too strict,
pkg_add will merge updates together to make sure
everything stays in sync. -D
dontmerge disables that behavior.
- 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.
-D donttie disables that
- Don't filter out package versions older than what's
- In update mode, reinstall an existing package with the
same update signature.
- Library specifications may not be fulfilled.
- Install even if not running as root.
- Very safe update: don't run any @exec/@unexec.
- Attempt to repair installed packages with missing
- External scripts may fail.
- 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.
- Allow the installation of unsigned packages without
warnings/errors (necessary for
ports(7), automatically set by the
- Force update even if forward dependencies no longer
- Force non-interactive mode. Default is to be interactive
when run from a tty.
- Force interactive mode, even if not run from a tty.
pkg_add may ask questions to the user if faced with
- 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
bsd.port.mk(5) for a description
- Installs packages from the raw output of
pkg_info(1), as saved in
file. Generally, use with
-m >file, to reproduce an installation from machine to machine.
With -z and -l
pkg_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.
- Causes pkg_add to always display the
progress meter in cases it would not do so by default.
- Don't actually install a package, just report the steps
that would be taken if it was. Will still copy packages to
PKG_CACHE if applicable.
- Check permissions for distribution, where
type can be ‘cdrom’ or
- Replace package quickly; do not bother with checksums
before removing normal files. If used twice, it will not bother with
checksums for configuration files either.
- 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 -D
update to force the replacement);
pkg_add will also refuse to replace packages when the
dependencies don't quite match (use -D
updatedepends 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.
- Update dependencies if required before installing the new
- Update the given installed
pkgname(s), and anything it depends upon. If no
pkgname is given, pkg_add will
update all installed packages. This relies on
PKG_PATH to figure out the new package names.
- Turn on verbose output. Several -v turn
on more verbose output. By default, pkg_add is almost
completely silent, but it reacts to keyboard status requests (see
stty(1)). -v turns on
basic messages, -vv adds relevant system operations,
-vvv shows most internal computations apart from
individual file/directory additions, -vvvv also shows
dependencies adjustments, and -vvvvv shows
- Disable progress meter.
- 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
By default, when adding packages via FTP, the
program operates in
“passive” mode. If you wish to use active mode instead, set the
environment variable to “active”.
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.
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
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
option will remove the ‘installed manually’
tag from installed packages.
can be used to show only
manually-installed packages, and
can be used to remove
dependencies when they are no longer needed.
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
to perform several installations/deletions
For each new package in an updateset, pkg_add
package's “packing information” (the packing-list, description,
and installation/deinstallation scripts) into a special staging directory in
if set) and
then runs through the following sequence to fully extract the contents of the
- 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
- 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.
- pkg_add checks for collisions with
installed file names, read-only file systems, and enough space to store
- 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
PKG_DBDIR is set, this
overrides the /var/db/pkg/ path shown above).
- Finally, the staging area is deleted and the program
Note that it is safe to interrupt pkg_add
, and other
signals, as it will safely record an interrupted install as
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
- 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
- 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
- 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
- Each package name is reduced to its stem, and every
package name with matching stem available through
PKG_PATH is considered as an update
- 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
- Version matching occurs: unless -D downgrade, only
packages with newer versions will be considered as update candidates. Note
that version matching is costly, thus
should point to a snapshot of packages for a given version of
OpenBSD, similar to the organization on the FTP
- 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
- If several candidates are left, pkg_add
will ask the user in interactive mode, and not perform the update in
- 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.
- Specifies whether ftp(1)
should operate in “active” or “passive” mode. The
default is “passive”.
- Override use of ftp(1).
Must point to a command that understands
- Have ftp(1) send a byte
FTP_KEEPALIVE seconds, so that
incorrectly configured network equipment won't aggressively drop it. See
“ftp -k” for more information.
- Where to register packages instead of
- Value for pkg-destdir, if no
-B option is specified.
- If set, any package retrieved from a distant location will
be copied to that directory as well.
- If a given package name cannot be found, the directories
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.
- Temporary area where package information files will be
extracted, instead of /var/tmp.
- Same semantics as
PKG_PATH, but it
is searched before
PKG_PATH and waves any kind of
- Initial design.
- Complete rewrite.