Skip to main content.

Binary packages with pkgng


Live demo in BSD Now Episode 003 | Originally written by TJ for | Last updated: 2014/03/14

NOTE: the author/maintainer of the tutorial(s) is no longer with the show, so the information below may be outdated or incorrect.

Binary packages - some love them, some hate them, some don't know anything else. While most of the BSDs have used the ports collection or pkgsrc to compile software from source code, they've also offered precompiled versions of that large collection of software. Sometimes you would rather trade away the flexibility, customization and other great features of the ports collection or pkgsrc for something that's more "quick 'n easy."

Since many years ago, FreeBSD, OpenBSD, NetBSD and DragonFlyBSD have used the "pkg_add" command to install binary packages. In August of 2012, however, the FreeBSD ports team released the first version of the next generation package management tool: pkgng

The old pkg_ toolset was getting a bit long in the tooth and didn't support a lot of the features that a modern package manager should have. The pkgng toolset fixes all this, while adding some of its own awesome new features that no other package managers have. This tutorial will show you the basic usage of the "pkg" utility. It was written with FreeBSD in mind, but DragonFlyBSD also supports pkgng. Maybe the other BSDs will adopt it as time goes on, too.

It may sound obvious, but before you start, you will need a binary package repository. You can use the official ones or look into making your own. The remainder of this document will assume you have a correctly-functioning and up-to-date repository configured. It should look something like this:

$ cat /usr/local/etc/pkg/repos/FreeBSD.conf

FreeBSD: {
  url: "pkg+${ABI}/latest",
  mirror_type: "srv",
  signature_type: "fingerprints",
  fingerprints: "/usr/share/keys/pkg",
  enabled: yes

If you're converting a system from the old style pkg_ utilities, you must discontinue use of them entirely. Also, run the following commands:

# echo "WITH_PKGNG=yes" >> /etc/make.conf
# pkg2ng

If you get a "command not found" error, make sure you are on a supported version of the OS, and install the pkgng utility via ports:

# cd /usr/ports/ports-mgmt/pkg
# make install clean

So, the basics (straight from running "pkg help") are:

add            Registers a package and installs it on the system
annotate       Add, modify or delete tag-value style annotations on packages
audit          Reports vulnerable packages
autoremove     Removes orphan packages
backup         Backs-up and restores the local package database
check          Checks for missing dependencies and database consistency
clean          Cleans old packages from the cache
convert        Convert database from/to pkgng
create         Creates software package distributions
delete         Deletes packages from the database and the system
fetch          Fetches packages from a remote repository
help           Displays help information
info           Displays information about installed packages
install        Installs packages from remote package repositories
lock           Locks package against modifications or deletion
plugins        Manages plugins and displays information about plugins
query          Queries information about installed packages
register       Registers a package into the local database
remove         Deletes packages from the database and the system
repo           Creates a package repository catalog
rquery         Queries information in repository catalogs
search         Performs a search of package repository catalogs
set            Modifies information about packages in the local database
ssh            ssh packages to be used via ssh
shell          Opens a debug shell
shlib          Displays which packages link against a specific shared library
stats          Displays package database statistics
unlock         Unlocks a package, allowing modification or deletion
update         Updates package repository catalogs
updating       Displays UPDATING information for a package
upgrade        Performs upgrades of packaged software distributions
version        Displays the versions of installed packages
which          Displays which package installed a specific file

As you can see, pkgng has quite a list of features and abilities. If you want more detail about any of the subcommands, you can use "pkg help $subcommand" to get more details. For example:

# pkg help install

While we're not going to go over every single subcommand and all of its features, we will cover all the parts you need for basic usage and package management. The most basic example to start with is installing a package. If I wanted to grab a precompiled binary of tmux, it's as simple as:

# pkg install tmux

Updating repository catalog
The following 2 packages will be installed:

    Installing libevent: 1.4.14b_2
    Installing tmux: 1.8_1

The installation will require 949 kB more space

270 kB to be downloaded

Proceed with installing packages [y/N]: y
libevent-1.4.14b_2.txz                  100%  119KB 118.7KB/s 118.7KB/s   00:00    
tmux-1.8_1.txz                          100%  152KB 152.2KB/s 152.2KB/s   00:00    
Checking integrity... done
[1/2] Installing libevent-1.4.14b_2... done
[2/2] Installing tmux-1.8_1... done

Doesn't get much more simple than that, does it? If I decided I wanted to live in some crazy alternate universe where I no longer wanted tmux installed on my system, it can be easily removed with:

# pkg remove tmux

Deinstallation has been requested for the following 1 packages:


The deinstallation will free 355 kB

Proceed with deinstalling packages [y/N]: y
[1/1] Deleting tmux-1.8_1... done

But wait, when I installed it before, it pulled in libevent as a dependency. To automatically purge all unused dependencies, use:

# pkg autoremove

Deinstallation has been requested for the following 1 packages:


The deinstallation will free 594 kB

Proceed with deinstalling packages [y/N]: y
[1/1] Deleting libevent-1.4.14b_2... done

This should keep your system clean of any cruft that was pulled in from things you installed once upon a time but no longer have a need for. If you want to list all the packages you currently have installed on your system, it can be done like so:

# pkg info

bash-4.2.45                    The GNU Project's Bourne Again SHell
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
gnupg-2.0.21                   The GNU Privacy Guard
libassuan-2.0.3                IPC library used by GnuPG and gpgme
libgcrypt-1.5.3                General purpose crypto library based on code used in GnuPG
libgpg-error-1.12              Common error values for all GnuPG components
libiconv-1.14_1                A character set conversion library
libidn-1.28                    Internationalized Domain Names command line tool
libksba-1.3.0                  KSBA is an X.509 Library
mime-support-3.54              MIME Media Types list
mutt-1.5.21_4                  The Mongrel of Mail User Agents (development version)
pkg-1.1.4_2                    New generation package manager
pth-2.0.7                      GNU Portable Threads
ssmtp-2.64                     Extremely simple MTA to get mail off the system to a mail hub
urlview-0.9_7                  URL extractor/launcher
vim-lite-7.3.1314_2            Vi "workalike", with many additional features (Lite package) 

Upgrading packages is very easy with pkgng. This command will bring all your installed packages up to date, while automatically resolving any new dependency issues and reinstalling anything that has been changed:

# pkg upgrade -y

Updating repository catalog
digests.txz                         100%   25KB  24.7KB/s  24.7KB/s   00:00    
packagesite.txz                     100%  126KB 125.6KB/s 125.6KB/s   00:00    
Incremental update completed, 0 packages processed:
133 packages updated, 0 removed and 8 added.
Upgrades have been requested for the following 2 packages:

        Upgrading python2: 2 -> 2_1
        Upgrading wireshark: 1.10.1 -> 1.10.2

The upgrade will free 1 MB

10 MB to be downloaded
python2-2_1.txz                     100% 2296     2.2KB/s   2.2KB/s   00:00    
wireshark-1.10.2.txz                100%   11MB   5.4MB/s   9.1MB/s   00:02    
Checking integrity... done
[1/2] Upgrading python2 from 2 to 2_1... done
[2/2] Upgrading wireshark from 1.10.1 to 1.10.2... done

To search your repository for certain ports (using "vim" as an example), you can use:

# pkg search vim


That's really all you need to know to get rolling with pkgng.

Latest News

New announcement


Hi, Mr. Dexter...

Two Year Anniversary


We're quickly approaching our two-year anniversary, which will be on episode 105. To celebrate, we've created a unique t-shirt design, available for purchase until the end of August. Shirts will be shipped out around September 1st. Most of the proceeds will support the show, and specifically allow us to buy...

New discussion segment


We're thinking about adding a new segment to the show where we discuss a topic that the listeners suggest. It's meant to be informative like a tutorial, but more of a "free discussion" format. If you have any subjects you want us to explore, or even just a good name...

How did you get into BSD?


We've got a fun idea for the holidays this year: just like we ask during the interviews, we want to hear how all the viewers and listeners first got into BSD. Email us your story, either written or a video version, and we'll read and play some of them for...

Episode 207: Bridge over the river Cam


Direct Download:HD VideoMP3 AudioTorrent This episode was brought to you by Headlines BSDCam recap The 2017 Cambridge DevSummit took place from 2-4 August 2017. The event took place over three days including a formal dinner at St John's College, and was attended by 55 registered developers and guests. Prior to the start of...

Episode 206: To hier is UNIX


HD VideoMP3 AudioTorrent This episode was brought to you by Headlines Lumina Desktop v1.3 released Notable Changes: New Utility: lumina-mediaplayer. Lumina Media Player is a graphic interface for the Qt QMediaPlayer Class, with Pandora internet radio streaming integration. Lumina Media Player supports many audio formats, including .ogg, .mp3, .mp4, .flac, and .wmv. It is also...

Episode 205: FreeBSD Turning it up to 11.1


Direct Download:HD VideoMP3 AudioTorrent This episode was brought to you by Headlines FreeBSD 11.1-RELEASE FreeBSD 11.1 was released on July 26th You can download it as an ISO or USB image, a prebuilt VM Image (vmdk, vhd, qcow2, or raw), and it is available as a cloud image (Amazon EC2, Microsoft Azure, Google Compute Engine,...

Episode 204: WWF - Wayland, Weston, and FreeBSD


Direct Download:HD VideoMP3 AudioTorrent This episode was brought to you by Headlines Matt Ahrens answers questions about the “Scrub of Death” In working on the breakdown of that ZFS article last week, Matt Ahrens contacted me and provided some answers he has given to questions in the past, allowing me to answer them using...