path: root/man/pkg.8

.Dd September 27, 2026
.Dt PKG 8
.Os
.Sh NAME
.Nm pkg
.Nd package manager for rawnix.org
.Sh SYNOPSIS
.Nm
.Op Fl bfNvy
.Op Fl r Ar root
.Ar command
.Op Ar argument ...
.Nm
.Fl h | V
.Sh DESCRIPTION
.Nm
installs, upgrades and removes packages together with their
dependencies.
It builds a package with
.Ic mkpkg -d
in the port directory, or fetches it with
.Xr bulk 8 ,
installs it with
.Xr addpkg 8
and removes it with
.Xr delpkg 8 .
For every installed package it records whether it was installed on
request or as a dependency, so that
.Cm autoremove
can remove dependencies nothing needs any more.
.Pp
Options may also follow the command.
The options are as follows:
.Bl -tag -width Ds
.It Fl b , Fl Fl use-bulk
Fetch pre-built packages with
.Xr bulk 8
instead of building, for
.Cm add ,
.Cm update
and
.Cm sysup .
A port with a
.Pa MAKEPKG.lock
is never fetched: it is built from the lock, and its build
dependencies are fetched.
If a fetch fails, nothing is built in its place.
.It Fl f , Fl Fl force
With
.Cm del ,
remove a package even though installed packages depend on it.
.It Fl h , Fl Fl help
Print a usage summary.
.It Fl N , Fl Fl no-deps
With
.Cm add
and
.Cm update ,
build or fetch and install only the named package, without resolving
its dependencies.
.It Fl r Ar root , Fl Fl root Ar root
Install into, and read the package databases of,
.Ar root
instead of
.Pa / .
Ports, configuration and builds are those of the running system.
.It Fl V , Fl Fl version
Print the version.
.It Fl v , Fl Fl verbose
With
.Cm prepare ,
print the port's dependencies first.
.It Fl y , Fl Fl yes
Answer yes to every confirmation.
A package that has variants is then an error, since the choice cannot
be made for you.
.El
.Sh COMMANDS
.Ss Installing and removing
.Bl -tag -width Ds
.It Cm add Ar port ...
Install each
.Ar port
with its dependencies, in the order given, and stop at the first
failure.
A package already installed at its port's version is left alone.
Either way it is recorded as installed on request.
.Pp
If ports named
.Ar port Ns - Ns Ar suffix
declare a
.Va variant ,
the choices are listed and one is asked for; see
.Sx PORTS .
.It Cm del Ar package ...
Remove each installed
.Ar package .
A package is not removed if it is locked, or if an installed package
depends on it and
.Fl f
is not given.
The other packages are still removed.
Afterwards the orphaned packages are listed.
.It Cm update Ar package ...
Update each installed
.Ar package ,
with its dependencies, to its port's version.
Unlike
.Cm add ,
it keeps the reason the package was installed for.
It stops at the first failure.
.It Cm sysup
Update every installed package whose version differs from its port.
Packages without a port, and locked packages without a
.Pa MAKEPKG.lock ,
are left alone.
The list is shown for confirmation, then worked through in order of
runtime dependencies.
With
.Fl b ,
.Ic bulk -u
runs first.
A package that fails is reported and skipped, and the others are
still updated.
.It Cm autoremove
Remove the orphaned packages, after confirmation.
Locked packages are kept.
.El
.Ss Building
.Bl -tag -width Ds
.It Cm build Op Ar port
Build the package of
.Ar port
without installing it, unless it is already built.
Without
.Ar port ,
the port is named by the
.Pa MAKEPKG
in the current directory.
.It Cm prepare Op Ar port
Install everything
.Ar port
needs to be built: its runtime and build dependencies, but not the
port itself.
Installed dependencies whose version differs from their port are
updated first.
New packages are recorded as dependencies, so
.Cm autoremove
removes them once nothing needs them.
Without
.Ar port ,
the port in the current directory is used.
.It Cm bulk Ar port ...
Fetch the packages of each
.Ar port
and its runtime dependencies with
.Xr bulk 8 ,
without installing them.
Locked ports are not fetched; for those that must be built, their
build dependencies are.
.El
.Ss Queries
.Bl -tag -width Ds
.It Cm list
List the installed packages with their versions.
.It Cm isinst Ar package
Print the name and version of
.Ar package
if it is installed, and exit 1 if it is not.
.It Cm diff
List the installed packages whose version differs from their port.
A locked package without a
.Pa MAKEPKG.lock
is marked
.Li [locked] .
For a port with a
.Pa MAKEPKG.lock ,
the line is marked
.Li [MAKEPKG.lock] ,
and
.Li upstream Ar version
is added when the port's
.Pa MAKEPKG
has moved on.
.It Cm depends Ar port
Print the
.Va depends
and
.Va makedeps
of the port's recipe.
Only the direct dependencies are shown.
.It Cm rdepends Ar package
List the packages whose runtime dependencies include
.Ar package .
.It Cm orphans
List the orphaned packages: those installed as a dependency that no
installed package depends on any more, directly or through other
orphans.
.El
.Ss Locking
.Bl -tag -width Ds
.It Cm lock Ar package
Lock an installed package.
The port's
.Pa MAKEPKG ,
.Pa .footprint
and
.Pa .signature
are copied to
.Pa MAKEPKG.lock ,
.Pa .footprint.lock
and
.Pa .signature.lock ,
which
.Xr ports 8
never changes.
An existing
.Pa MAKEPKG.lock
is kept.
.Pp
.Nm
and
.Xr mkpkg 8
use
.Pa MAKEPKG.lock
whenever it exists.
Upstream changes to the port are therefore ignored, while edits to
.Pa MAKEPKG.lock
are built and installed by
.Cm add ,
.Cm update ,
.Cm sysup
and
.Cm prepare .
.Pp
If the package has no port, only the installed version is pinned: it
is never upgraded, and
.Cm add
refuses it.
.Pp
Locked packages are never removed by
.Cm del
or
.Cm autoremove .
.It Cm unlock Ar package
Unlock
.Ar package
and remove the three lock files from its port.
.It Cm locked
List the locked packages with their installed versions.
Where the recipe's version differs, it is added as
.Li -> lock Ar version
or, without a
.Pa MAKEPKG.lock ,
.Li -> repo Ar version .
.Li [stale]
marks a package that is no longer installed,
.Li [no MAKEPKG.lock]
a port without the lock file.
.El
.Ss Dependency database
.Bl -tag -width Ds
.It Cm initdb
Add every installed package that the dependency database does not
know yet, as installed on request, and fill in missing dependency
lists from the ports.
The first
.Nm
command run with an empty database does this by itself.
.It Cm checkdb
Report entries for packages that are no longer installed, and
installed packages that are not in the database, and offer to remove
the former.
.El
.Ss Other
.Bl -tag -width Ds
.It Cm help
Same as
.Fl h .
.It Cm version
Same as
.Fl V .
.El
.Sh PORTS
A port is a directory holding a
.Pa MAKEPKG ,
or only a
.Pa MAKEPKG.lock ,
in one of the port directories of
.Xr pkg.conf 5 .
Its name is the directory's name, and the recipe's
.Va name
must be the same: the package file is found by that name.
A port where they differ is refused with an error.
If two port directories have a port of the same name, the one listed
later is used.
.Pp
.Nm
reads the recipe that
.Xr mkpkg 8
builds:
.Pa MAKEPKG.lock
if it exists, otherwise
.Pa MAKEPKG .
Besides
.Va name ,
.Va version
and
.Va release
it uses these arrays, described in
.Xr MAKEPKG 5 :
.Bl -tag -width makedeps
.It Va depends
Needed at run time.
Always installed with the package, and recorded in the dependency
database.
.It Va makedeps
Needed only to build.
Installed only for a package that has to be built, that is, not
already built and not fetched with
.Fl b .
.It Va provides
Other names this port satisfies as a dependency.
A dependency on such a name is met by an installed port providing
it; if none is installed, a providing port is installed.
.It Va variant
A one-line description.
A port
.Ar name Ns - Ns Ar suffix
that sets it is offered as a variant of
.Ar name
by
.Cm add .
.El
.Pp
A package counts as built if the file
.Sm off
.Ar name No # Ar version No - Ar release No .pkg.tar.\& Ar ext
.Sm on
exists in the package directory
.Ev MKPKG_PACKAGE_DIR
of
.Pa /etc/mkpkg.conf ,
or in the port directory.
.Pp
Installed dependencies whose version differs from their port are
updated before the package that needs them.
Packages without a port, such as a kernel built from
.Pa /usr/src ,
and locked packages without a
.Pa MAKEPKG.lock
are used as they are.
.Pp
When dependencies form a cycle, packages in it that are already
installed are rebuilt against the installed versions of the others.
A cycle through a package that is not installed is an error.
.Sh CONCURRENCY
Commands that change the system or a database take the lock
.Pa /var/lib/pkg/pkg.lock
and wait for another
.Nm
holding it.
Queries do not.
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /etc/pkg.conf
Port directories; see
.Xr pkg.conf 5 .
.It Pa /etc/mkpkg.conf
Read for
.Ev MKPKG_PACKAGE_DIR
and
.Ev MKPKG_COMPRESSION_MODE ;
see
.Xr mkpkg.conf 5 .
.It Pa /var/lib/pkg/db
Package database, written by
.Xr addpkg 8
and
.Xr delpkg 8 .
.It Pa /var/lib/pkg/deps.db
Dependency database: why each package was installed, and its runtime
dependencies.
.It Pa /var/lib/pkg/locked
Locked packages.
.It Pa /var/lib/pkg/pkg.lock
Instance lock.
.El
.Sh EXIT STATUS
.Ex -std
.Cm del ,
.Cm sysup
and
.Cm autoremove
fail if any package failed.
.Sh EXAMPLES
Install with dependencies, then remove:
.Bd -literal -offset indent
# pkg add firefox
# pkg del firefox
.Ed
.Pp
Update the whole system from pre-built packages without asking:
.Pp
.Dl # pkg -by sysup
.Pp
Install the build dependencies of the port in the current directory:
.Pp
.Dl # pkg prepare
.Pp
Keep rust at its current recipe:
.Pp
.Dl # pkg lock rust
.Sh SEE ALSO
.Xr MAKEPKG 5 ,
.Xr mkpkg.conf 5 ,
.Xr pkg.conf 5 ,
.Xr addpkg 8 ,
.Xr bulk 8 ,
.Xr delpkg 8 ,
.Xr infopkg 8 ,
.Xr mkpkg 8 ,
.Xr ports 8 ,
.Xr revdep 8
.Sh CAVEATS
With
.Fl r ,
.Ic bulk -u
in
.Cm sysup Fl b
still compares against the running system's package database.