4.4. Using pkg for Binary Package Management
Prev | Chapter 4. Installing Applications: Packages and Ports | Next

## 4.4. Using pkg for Binary Package Management

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.

### 4.4.1. Getting Started with pkg

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 10.`X`.

### Note:

Not all FreeBSD versions and architectures support this bootstrap process. The current list is at https://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:

    # /usr/sbin/pkg

You must have a working Internet connection for the bootstrap process to succeed.

Otherwise, to install the port, run:

    # cd /usr/ports/ports-mgmt/pkg
    # make
    # 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:

    # pkg2ng

### Note:

This step is not required for new installations that do not yet have any third-party software installed.

### Important:

This step is not reversible. Once the package database has been converted to the pkg format, the traditional `pkg_*` tools should no longer be used.

### Note:

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 `pkg2ng` finishes. 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 10.`X` require this line in `/etc/make.conf`:

    WITH_PKGNG=	yes

By default, pkg uses the binary packages from the FreeBSD package mirrors (the repository). For information about building a custom package repository, see Section 4.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

    # man pkg-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.

### 4.4.2. Obtaining Information About Installed Packages

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 package.

For example, to see which version of pkg is installed, run:

    # pkg info pkg
    pkg-1.1.4_1

### 4.4.3. Installing and Removing Packages

To install a binary package use the following command, where `packagename` is the name of the package to install:

    # pkg install packagename

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 curl
    Updating 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]: y
    Checking 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 info
    ca_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 curl
    The 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

### 4.4.4. Upgrading Installed Packages

Installed packages can be upgraded to their latest versions by running:

    # pkg upgrade

This command will compare the installed versions with those available in the repository catalogue and upgrade them from the repository.

### 4.4.5. Auditing Installed Packages

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

### 4.4.6. Automatically Removing Unused Packages

Removing a package may leave behind dependencies which are no longer required. Unneeded packages that were installed as dependencies (leaf packages) can be automatically detected and removed using:

    # pkg autoremove
    Packages to be autoremoved:
    	ca_root_nss-3.15.1_1

    The autoremoval will free 723 kB

    Proceed with autoremoval of packages [y/N]: y
    Deinstalling ca_root_nss-3.15.1_1... done

Packages installed as dependencies are called automatic packages. Non-automatic packages, i.e the packages that were explicity installed not as a dependency to another package, can be listed using:

    # pkg prime-list
    nginx
    openvpn
    sudo

`pkg prime-list` is an alias command declared in `/usr/local/etc/pkg.conf`. There are many others that can be used to query the package database of the system. For instance, command `pkg prime-origins` can be used to get the origin port directory of the list mentioned above:

    # pkg prime-origins
    www/nginx
    security/openvpn
    security/sudo

This list can be used to rebuild all packages installed on a system using build tools such as ports-mgmt/poudriere or ports-mgmt/synth.

Marking an installed package as automatic can be done using:

    # pkg set -A 1 devel/cmake

Once a package is a leaf package and is marked as automatic, it gets selected by `pkg autoremove`.

Marking an installed package as not automatic can be done using:

    # pkg set -A 0 devel/cmake

### 4.4.7. Restoring the Package Database

Unlike the traditional package management system, pkg includes its own package database backup mechanism. This functionality is enabled by default.

### Tip:

To disable the periodic script from backing up the package database, set `daily_backup_pkgdb_enable="NO"` in periodic.conf(5).

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 /path/to/pkg.sql

### Note:

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 command, replacing `/path/to/pkg.sql` with a suitable file name and location:

    # pkg backup -d /path/to/pkg.sql

### 4.4.8. Removing Stale Packages

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:

    # pkg clean

The entire cache may be cleared by running:

    # pkg clean -a

### 4.4.9. Modifying Package Metadata

Software within the FreeBSD Ports 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 represent version `5.4`.

To change the package origin for the above example, run:

    # pkg set -o lang/php5:lang/php53

As another example, to update lang/ruby18 to lang/ruby19, run:

    # pkg set -o lang/ruby18:lang/ruby19

As a final example, to change the origin of the `libglut` shared libraries from graphics/libglut to graphics/freeglut, run:

    # pkg set -o graphics/libglut:graphics/freeglut

### Note:

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 graphics/freeglut

Prev | Up | Next
4.3. Finding Software | Home | 4.5. Using the Ports Collection

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.