pkg is the next generation replacement for the traditional FreeBSD package management tools, offering many features that make dealing with binary packages faster and easier.
For sites wishing to only use prebuilt binary packages from the FreeBSD mirrors, managing packages with pkg can be sufficient.
However, for those sites building from source or using their own repositories, a separate port management tool will be needed.
Since pkg only works with binary packages, it is not a replacement for such tools. Those tools can be used to install software from both binary packages and the Ports Collection, while pkg installs only binary packages.
FreeBSD includes a bootstrap utility which can be used to
download and install pkg
and its manual pages. This utility is designed to work
with versions of FreeBSD starting with
Not all FreeBSD versions and architectures support this bootstrap process. The current list is at http://pkg.freebsd.org/. For other cases, pkg must instead be installed from the Ports Collection or as a binary package.
To bootstrap the system, run:
You must have a working Internet connection for the bootstrap process to succeed.
Otherwise, to install the port, run:
make install clean
When upgrading an existing system that originally used the older pkg_* tools, the database must be converted to the new format, so that the new tools are aware of the already installed packages. Once pkg has been installed, the package database must be converted from the traditional format to the new format by running this command:
This step is not required for new installations that do not yet have any third-party software installed.
This step is not reversible. Once the package database
has been converted to the pkg
format, the traditional
should no longer be used.
The package database conversion may emit errors as the
contents are converted to the new version. Generally, these
errors can be safely ignored. However, a list of
software that was not successfully converted
is shown after
These applications must be manually reinstalled.
To ensure that the Ports Collection registers
new software with pkg instead of
the traditional packages database, FreeBSD versions earlier than
X require this line in
By default, pkg uses the binary packages from the FreeBSD package mirrors (the repository). For information about building a custom package repository, see Section4.6, “Building Packages with Poudriere”.
Additional pkg configuration options are described in pkg.conf(5).
Usage information for pkg is
available in the pkg(8) manual page or by running
pkg without additional arguments.
Each pkg command argument is
documented in a command-specific manual page. To read the
manual page for
pkg install, for example,
run either of these commands:
pkg help install
The rest of this section demonstrates common binary package management tasks which can be performed using pkg. Each demonstrated command provides many switches to customize its use. Refer to a command's help or man page for details and more examples.
Information about the packages installed on a system
can be viewed by running
pkg info which,
when run without any switches, will list the package version
for either all installed packages or the specified
For example, to see which version of pkg is installed, run:
pkg info pkgpkg-1.1.4_1
To install a binary package use the following command,
packagename is the name of
the package to install:
This command uses repository data to determine which version of the software to install and if it has any uninstalled dependencies. For example, to install curl:
pkg install curlUpdating repository catalogue /usr/local/tmp/All/curl-7.31.0_1.txz 100% of 1181 kB 1380 kBps 00m01s /usr/local/tmp/All/ca_root_nss-3.15.1_1.txz 100% of 288 kB 1700 kBps 00m00s Updating repository catalogue The following 2 packages will be installed: Installing ca_root_nss: 3.15.1_1 Installing curl: 7.31.0_1 The installation will require 3 MB more space 0 B to be downloaded Proceed with installing packages [y/N]:
yChecking integrity... done [1/2] Installing ca_root_nss-3.15.1_1... done [2/2] Installing curl-7.31.0_1... done Cleaning up cache files...Done
The new package and any additional packages that were installed as dependencies can be seen in the installed packages list:
pkg infoca_root_nss-3.15.1_1 The root certificate bundle from the Mozilla Project curl-7.31.0_1 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers pkg-1.1.4_6 New generation package manager
Packages that are no longer needed can be removed with
pkg delete. For example:
pkg delete curlThe following packages will be deleted: curl-7.31.0_1 The deletion will free 3 MB Proceed with deleting packages [y/N]:
y[1/1] Deleting curl-7.31.0_1... done
Installed packages can be upgraded to their latest versions by running:
This command will compare the installed versions with those available in the repository catalogue and upgrade them from the repository.
Software vulnerabilities are regularly discovered in third-party applications. To address this, pkg includes a built-in auditing mechanism. To determine if there are any known vulnerabilities for the software installed on the system, run:
pkg audit -F
Removing a package may leave behind dependencies which are no longer required. Unneeded packages that were installed as dependencies can be automatically detected and removed using:
pkg autoremovePackages to be autoremoved: ca_root_nss-3.15.1_1 The autoremoval will free 723 kB Proceed with autoremoval of packages [y/N]:
yDeinstalling ca_root_nss-3.15.1_1... done
Unlike the traditional package management system, pkg includes its own package database backup mechanism. This functionality is enabled by default.
To disable the periodic script from backing up the
package database, set
To restore the contents of a previous package database
backup, run the following command replacing
/path/to/pkg.sql with the location
of the backup:
pkg backup -r
If restoring a backup taken by the periodic script, it must be decompressed prior to being restored.
To run a manual backup of the
pkg database, run the following
with a suitable file name and location:
pkg backup -d
By default, pkg stores
binary packages in a cache directory defined by
PKG_CACHEDIR in pkg.conf(5). Only copies
of the latest installed packages are kept. Older versions of
pkg kept all previous packages. To
remove these outdated binary packages, run:
The entire cache may be cleared by running:
pkg clean -a
Software within the FreeBSDPorts Collection can
undergo major version number changes. To address this,
pkg has a built-in command to
update package origins. This can be useful, for example, if
lang/php5 is renamed to
lang/php53 so that
lang/php5 can now
To change the package origin for the above example, run:
pkg set -o lang/php5:lang/php53
pkg set -o lang/ruby18:lang/ruby19
pkg set -o graphics/libglut:graphics/freeglut
When changing package origins, it is important to reinstall packages that are dependent on the package with the modified origin. To force a reinstallation of dependent packages, run:
pkg install -Rf