Managing packages with pkg and the Ports Collection

FreeBSD has two distinct paths for installing software: pkg, a binary package manager for fast, pre-built installs, and the Ports Collection, a tree of build recipes under /usr/ports for compiling software from source with custom options. They’re related – ports are actually what the official binary packages are built from – but they solve different problems, and it’s worth understanding both before you decide which to reach for.

pkg: binary packages, the fast path

For the vast majority of software you’ll want on a VPS, pkg is the right tool. It downloads pre-compiled packages from FreeBSD’s package repositories and installs them in seconds, with dependency resolution handled automatically – much like apt or dnf on Linux, though the command syntax is its own.

The first time you run any pkg command on a fresh install, FreeBSD will offer to bootstrap the pkg tool itself – accept that, then you’re ready to go.

# Update the local copy of the package repository catalogue
pkg update

# Search for a package by name
pkg search nginx

# Install a package
pkg install nginx

# List packages currently installed
pkg info

# Upgrade all installed packages to their latest versions
pkg upgrade

# Remove a package
pkg delete nginx

# Remove packages that were only installed as dependencies and are no longer needed
pkg autoremove

# Clean up cached package files
pkg clean

That’s the whole day-to-day workflow. pkg install, pkg upgrade, and pkg delete will cover nearly everything you need to run a typical web server, mail server, or application host.

The Ports Collection: building from source

The Ports Collection is a tree of directories under /usr/ports, one per piece of software, each containing a Makefile and metadata describing how to fetch the software’s source code, patch it for FreeBSD, and compile it. It’s not installed by default – you fetch it with Git, since FreeBSD’s older ports snapshot tool, portsnap, has been retired in favour of Git as the single distribution method for the ports tree:

# Fetch the ports tree for the first time
git clone https://git.FreeBSD.org/ports.git /usr/ports

# Update it later
cd /usr/ports && git pull

To build and install a port, change into its directory and run make install clean:

cd /usr/ports/www/nginx
make install clean

If the port has configurable compile-time options, you’ll typically be shown a dialog letting you tick or untick them before the build starts – this is the whole point of using ports instead of the pre-built package, since the official binary package for a given piece of software is built with one fixed set of options. You can also review or change a port’s options without building straight away:

cd /usr/ports/www/nginx
make config

Which one should you actually use?

Honestly, for almost everything: use pkg. It’s faster, it doesn’t tie up your VPS’s CPU compiling software, and the default build options for official packages are sensible for most use cases. Reach for the Ports Collection specifically when:

• You need a compile-time option the binary package doesn’t offer – for example, a module built into nginx or Apache at compile time that isn’t in the default package build.
• You need a specific version, or a patch applied, that isn’t available as a package.
• You’re building something niche enough that no binary package exists for it at all.

One important caveat: don’t mix the two carelessly. Installing the same software both as a pkg package and as a hand-built port on the same system can cause version and dependency conflicts. Pick one approach per piece of software, and if you switch a package to a ports-built version, remove the packaged version first with pkg delete.