How to Use the Pkg Package Manager on FreeBSD 12
FreeBSD is an open source Unix-like operating system used to power modern servers, desktops, and embedded platforms. Giants like Netflix, Yahoo!, WhatsApp, BBC, and Sony use FreeBSD in some form. The FreeBSD system is not as widely known as Linux, largely because Linux has focused for many years on the Desktop and the FreeBSD project has tended to be more server based.
In this guide, you will learn about package management on FreeBSD 12.
Ports vs. Packages
On FreeBSD we have two different ways to install add-on software: via the Ports Collection, or Ports, and via pre-configured packages to install and manage software.
Ports is a system for building additional software on FreeBSD. With Ports you start with the raw source code provided by the software vendor and build the software in exactly the way you need, enabling and disabling features as you need.
Packages are pre-compiled software, and they are the result of building ports, using the options the port maintainer thinks will be most useful to the widest variety of people and bundling them up in a package to make them easily installable. Packages let you quickly install, uninstall, and upgrade add-on software. FreeBSD's packaging system is called package, or
pkg. Package information gets stored in an SQLite database that you can query about package data.
Another important thing about FreeBSD package management is the location of package binaries. Packages install binaries under
/usr/local, and most configuration files end up in
/usr/local/etc rather than
/etc. If you come from Linux world you may find this very uncommon.
The FreeBSD package manager,
The next generation replacement for the traditional FreeBSD package management tools is
pkg. Offering many features that make dealing with binary packages faster and easier,
pkg is the easiest way to install software that isn’t already included in the base system of FreeBSD. It is a single program with many subcommands that you will use for just about every operation on packages such as installing, removing and investigating packages. All package operations and changes must be run as
root or via
Here is how you would install the
curl package on FreeBSD:
pkg install curl
You can feed the command with
-y to avoid the
Proceed with this action? [y/N]: question when installing software or you can configure
pkg to always assume
-y in a configuration file.
To remove the package, you would use
pkg delete curl
As you can see, it is very simple and intuitive.
pkg help for a quick reference on the available subcommands, or
pkg help <subcommand> to display the manual page for a particular subcommand:
pkg help install
pkg help delete
The stock version of FreeBSD doesn't ship with the
pkg package manager installed. The first time you try to install some package,
pkg prompts you to install the package management tool. For example, let's say the first package you want to install on your fresh FreeBSD is
wget, and you will see the following prompt in your terminal:
The package management tool is not yet installed on your system.
Do you want to fetch and install it now? [y/N]: y
You will hit Y and Enter and the package management tool installation will start. After it is in place, the initial software package that you wanted to install (
wget) will be installed.
You can also install the packaging system on its own, without adding other packages, by running
pkg bootstrap. Additionally,
pkg knows how to install and update itself and other packages.
NOTE: Vultr instances have
pkg installed by default, so you don't need to install it.
pkg program is designed to be highly flexible, with each subcommand having many options. You can establish customized, but consistent behavior for most programs with the system-wide configuration file for
pkg, located in
The file contains commented-out defaults for
pkg. Just by reading that file, you can learn a lot about how
pkg behaves. The configuration is written in universal configuration language (UCL) and there is plenty of commented-out configuration options and quite a few aliases. Variables can be set to an integer, a string, or a Boolean value:
#PKG_DBDIR = "/var/db/pkg";
#PKG_CACHEDIR = "/var/cache/pkg";
#PORTSDIR = "/usr/ports";
#INDEXDIR = "";
#INDEXFILE = "INDEX-10"; # Autogenerated
#HANDLE_RC_SCRIPTS = false;
#DEFAULT_ALWAYS_YES = false;
#ASSUME_ALWAYS_YES = false;
. . .
You can define aliases for
pkg subcommands in
pkg.conf. At the bottom of
pkg.conf, you’ll find a section labeled
ALIAS. When you find yourself repeatedly running complex commands, you should add aliases.
For more information on the file format and options, you can refer to the
pkg.conf(5) man page:
Now that you have a package manager installed, you can install packages. If you are a sys-admin, you are familiar with the fact that different operating systems assign different names to packaged versions of the same software. A package for Apache web server on FreeBSD, for example, will have a completely different name than the packaged Apache on different Linux distributions. So, before you can install anything, you’ll need to figure out what the name of the package you want to install is.
The FreeBSD Project offers several sets of packages in a public repository, and they are updated every few days. There are currently over 25,000 packages.
For example, let's try to search for Apache web server:
pkg search apache
# apache24-2.4.38 Version 2.4.x of Apache web server
It will find all packages with
apache in their names. This will return a long list, but what you are looking for is the
apache24 package. There is a short description of every package. This should help you when deciding what package to install, but it's not always simple.
Some searches can generate hundreds of results. You will need to utilize different command line options to trim or adjust the search results. Consult the
pkg-search man page or help page
pkg help search to learn more about common search options.
If you’re not sure whether a package is what you really want you can use the following command to look up details of the package:
pkg search -R apache24
# name: "apache24"
# origin: "www/apache24"
# version: "2.4.38"
# comment: "Version 2.4.x of Apache web server"
# maintainer: "apache@FreeBSD.org"
# www: "https://httpd.apache.org/"
# abi: "FreeBSD:12:amd64"
# arch: "freebsd:12:x86:64"
# prefix: "/usr/local"
# . . .
# . . .
This command will give you a lot of useful information about the package.
To install software, use the
install subcommand and the name of a package to install:
pkg install apache24
When you install packages with
pkg consults the local package catalog, then downloads the requested package from the repository at
pkg.FreeBSD.org. Once the package is installed, it’s registered in an SQLite database kept in
/var/db/pkg/local.sqlite. Take care not to delete this file, otherwise, your system will lose track of which packages have been installed. If the software has dependencies,
pkg will figure them out and install them along with the base package. Packages installed as dependencies are called automatic packages.
The package manager has the ability to just download packages over the internet and save them in one location on the disk. This allows you to install them at another time. You can use the
pkg fetch command to download the package without installing it:
pkg fetch nginx
This command will fetch just Nginx without its dependencies. You can use the
-d flag to grab all the dependencies as well as the named package:
pkg fetch -d nginx
The packages are downloaded to the package cache directory
/var/cache/pkg. After you have fetched packages,
pkg will add them to this directory. You can list files to see what it contains:
Now, to install a downloaded package after a fetch, run
pkg install normally. The installation process uses the cached files rather than the downloaded ones.
Over time, the package cache directory can grow big. The
pkg clean command removes any cached packages that have been replaced by newer versions, as well as any package files that are no longer in the repository:
If you want to remove all cached packages, use the
pkg clean -a
If you want to clean the package cache automatically after each package install or upgrade, set the
Obtaining information about installed packages
If you forget which packages you’ve installed on a system you can use
pkg info to get a complete list of installed software:
# atk-2.28.1 GNOME accessibility toolkit (ATK)
# avahi-app-0.7_2 Service discovery on a local network
# ca_root_nss-3.42.1 Root certificate bundle from the Mozilla Project
# . . .
# . . .
If you want more information about an installed package, use
pkg info and the package name. This shows the package installation details in a human-friendly report:
pkg info nginx
# Name : nginx
# Version : 1.14.2_3,2
# . . .
# . . .
You can see a lot of useful information like the version of the software, the time of software installation, software license, compile-time flags and more. Check the
pkg-info man page for the complete details.
To uninstall binary packages use the
pkg delete subcommand. It’s also available as
pkg delete nginx
pkg remove nginx
You will get a list of packages to be removed and how much space this will free up.
If you remove a package that other packages depend on,
pkg removes the depending packages as well.
There may be a time when you want a package on your server to never upgrade. When you lock a package,
pkg won’t upgrade, downgrade, uninstall or reinstall it. It applies the same rules to the package’s dependencies and the programs it depends on.
pkg lock to lock a package:
pkg lock openssl
openssl package is now locked.
To list all currently locked packages on the system, use the
pkg lock -l
To remove the lock use the
pkg unlock command:
pkg unlock openssl
To lock or unlock all packages on the system at once, use the
pkg lock -a
pkg unlock -a
Package repositories are supported by
pkg, which are named collections of packages. You can add, remove, enable, and disable repositories. You should configure each repository in its own file using UCL format. Official FreeBSD repositories belong in the
/etc/pkg directory. FreeBSD ships with the repo "FreeBSD" enabled. You’ll find its configuration file in
You can add and remove repositories as needed. As
/etc/pkg is reserved for official FreeBSD repositories, you’ll need another directory. The traditional location is
/usr/local/etc/pkg/repos. If you want to use a different directory, you’ll need to set a location in
pkg.conf with the
REPO_DIRS option. The local repository directory doesn’t exist by default, so you’ll need to create it with
mkdir -p /usr/local/etc/pkg/repos. Put your own repository configurations in that directory.
This section will list some of the most frequently used subcommands that you will most likely use when administering a FreeBSD server:
# Installs a package without asking any questions
pkg install -y package
# Makes a backup of the local package database
# Lists all installed packages
# Shows extended information for a package
pkg info package
# Searches package repository
pkg search -i package
# Shows packages with known security vulnerabilities
pkg audit -F
# Shows which package owns the named file
pkg which file
# Removes unused packages
# Uninstalls a package
pkg delete package
# Removes cached packages from /var/cache/pkg
pkg clean -ay
# Updates local copy of the package catalog
# Upgrades installed packages to their latest version
# Checks the integrity of all your packages
pkg check -saq
# Verifies that a package's files are unaltered
pkg check -s nginx
# Shows what files came with the package
pkg info -l nginx
# Lists non-automatic packages
Important files and directories
pkgconfiguration file -
- Directory reserved for official FreeBSD repositories -
- FreeBSD repository file -
- Traditional location for custom repositories -
- Package cache directory -
- SQLite database -
FreeBSD provides two complementary technologies for installing third-party software: the FreeBSD Ports Collection, for installing from source and packages, for installing from pre-built binaries. As FreeBSD is shifting the system more decisively toward universal package management, try to manage third-party software with
pkg to the extent possible. Avoid using ports unless the software you want has no packaged version or you need to customize compile-time options.