.Dd September 27, 2026
.Dt ADDPKG 8
.Os
.Sh NAME
.Nm addpkg
.Nd install or upgrade a package
.Sh SYNOPSIS
.Nm
.Op Fl fu
.Op Fl r Ar root
.Ar package
.Nm
.Fl h | v
.Sh DESCRIPTION
.Nm
installs the package archive
.Ar package ,
as built by
.Xr mkpkg 8 .
Name and version are taken from the file name,
.Sm off
.Ar name No # Ar version No - Ar release No .pkg.tar.\& Ar ext .
.Sm on
It must be run as root.
.Pp
The installation runs these steps, in order:
.Bl -enum -offset indent
.It
Check the package against its footprint; see
.Sx FOOTPRINT GUARD .
.It
Lock the package database.
Refuse if the same version is installed, if another version is
installed and
.Fl u
is not given, or if
.Fl u
is given and the package is not installed.
.It
Refuse if a file in the package belongs to another installed package.
Directories may be shared.
.It
Create the groups and users declared in the package metadata, so that
files can be owned by them.
.It
Extract the archive; see
.Sx CONFIGURATION FILES .
.It
On upgrade, remove files of the old version that the new one no longer
has, unless another package owns them.
Files under
.Pa etc/
are kept and reported.
.It
Record the package in the database.
.It
Run
.Xr ldconfig 8
if the root has
.Pa /sbin/ldconfig ,
then the triggers; see
.Sx TRIGGERS .
.It
Enable the declared services, then apply the declared permissions and
file capabilities.
User and group names in the permissions are looked up in the root's
.Pa /etc/passwd
and
.Pa /etc/group .
.El
.Pp
The metadata is described under
.Va groups ,
.Va services ,
.Va permissions
and
.Va capabilities
in
.Xr MAKEPKG 5 .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl f
Force: skip the footprint guard, allow file conflicts, and reinstall a
version that is already installed.
Forcing a different version than the installed one is an upgrade, as
with
.Fl u .
.It Fl h
Print a usage summary.
.It Fl r Ar root
Install into
.Ar root
instead of
.Pa / .
Groups, users and triggers are handled by commands run with
.Xr chroot 8
into
.Ar root .
.It Fl u
Upgrade an installed package to a different version.
.It Fl v
Print the version.
.El
.Sh FOOTPRINT GUARD
If the directory holding
.Ar package
also holds a
.Pa .footprint ,
the package is compared with it before anything is installed.
If that directory is a locked port, with a
.Pa MAKEPKG.lock ,
.Pa .footprint.lock
is used instead.
Without a footprint file the check is skipped.
A footprint file that cannot be read, or a package whose contents
cannot be listed, blocks the installation.
.Pp
Entries are reported under
.Dq changed ,
.Dq missing
and
.Dq new .
Changed and missing entries always block the installation.
New entries block it unless
.Li IGNORE_NEW=yes
is set in
.Pa /etc/mkpkg.conf .
.Fl f
skips the check.
.Sh CONFIGURATION FILES
On a fresh install every file is extracted.
.Pp
On an upgrade, a file under
.Pa etc/
that already exists is left alone and the new one is placed beside it
as
.Pa file.new ,
unless the two are identical.
The staged files are listed.
.Pp
On a forced reinstall of the same version, existing files under
.Pa etc/
are not touched; missing ones are installed.
They stay in the database either way.
.Sh TRIGGERS
After the files are in place,
.Nm
runs a command for each kind of path the operation added or removed.
Each command runs at most once, is announced on standard error, and is
skipped quietly if it is not installed.
.Bl -tag -width Ds
.It Pa lib/modules/ Ns Ar version Ns /
.Ic depmod -a Ar version ,
for each version whose directory exists.
.It Pa boot/ , usr/share/limine/
.Ic limine-sync .
.It Pa usr/lib/udev/hwdb.d/ , etc/udev/hwdb.d/
.Ic systemd-hwdb update .
.It Pa usr/share/fonts/
.Ic fc-cache -s .
.It Pa usr/share/glib-2.0/schemas/
.Ic glib-compile-schemas .
.It Pa usr/lib/gdk-pixbuf-2.0/
.Ic gdk-pixbuf-query-loaders --update-cache .
.It Pa usr/share/mime/
.Ic update-mime-database .
.It Pa usr/share/icons/
.Ic gtk-update-icon-cache -q /usr/share/icons/hicolor .
.It Pa usr/share/applications/
.Ic update-desktop-database .
.It Pa etc/sv/ Ns Ar service Ns /
On upgrade only:
.Ic sv restart /etc/sv/ Ns Ar service ,
if the service is running.
.El
.Sh ENVIRONMENT
.Bl -tag -width PKG_DBDIR
.It Ev PKG_ROOT
Installation root if
.Fl r
is not given.
.It Ev PKG_DBDIR
Package database directory.
An absolute path is used as it is, a relative one below the root.
Default:
.Pa /var/lib/pkg .
.It Ev TMPDIR
Directory for temporary files.
Default:
.Pa /tmp .
.El
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /var/lib/pkg/db
Package database.
.It Pa /var/lib/pkg/meta/ Ns Ar name
Package metadata.
.It Pa /etc/mkpkg.conf
Read for
.Li IGNORE_NEW ;
see
.Xr mkpkg.conf 5 .
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Install a freshly built package from its port directory:
.Pp
.Dl # addpkg /usr/ports/core/zlib/zlib#1.3.1-1.pkg.tar.gz
.Pp
Upgrade it:
.Pp
.Dl # addpkg -u /usr/ports/core/zlib/zlib#1.3.2-1.pkg.tar.gz
.Sh SEE ALSO
.Xr MAKEPKG 5 ,
.Xr mkpkg.conf 5 ,
.Xr delpkg 8 ,
.Xr infopkg 8 ,
.Xr mkpkg 8 ,
.Xr pkg 8