Skip to main content.

The FreeBSD Ports Collection


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

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

So you've just finished installing your new FreeBSD system. What now? While the base OS includes quite a lot of useful utilities, you're probably going to need to install some third party software. Depending on the usage of the machine, you might need a web server, a graphical desktop or anything in between. One of the best features of BSD is that there is a clear separation between the base system and external software. This keeps things very organized. There are (at least) two ways to install third party software: with binary packages or with ports. This tutorial will show you how to use the source-based ports collection to install and manage applications.

Jordan Hubbard committed what would become the legendary ports system on August 21, 1994. Since then, it's grown to become the most powerful and flexible way to manage software. It's been copied and imitated by others, and is the basis of OpenBSD's ports, NetBSD's pkgsrc, DragonFlyBSD's dports and even Gentoo Linux's portage. As you can see, it's pretty awesome - and people recognize that.

Installing and uninstalling

The way it works is like this: you have a collection of makefiles and patches stored locally on your system. This is called the "ports tree." By following the directions in those makefiles, FreeBSD is able to automatically download the source code for third party programs, apply any patches that are needed to make it build cleanly, compile the software and finally package it up for you. A lot of magic is going on behind the scenes when you type "make install clean." The ports collection provides a way to customize every package you install, from the CFLAGS to the options you want enabled or disabled. Let's get started by getting a copy of the ports tree. We'll be using the portsnap command which is included in the base OS.

# portsnap fetch extract

Looking up mirrors... 7 mirrors found.
Fetching public key from done.
Fetching snapshot tag from done.
Fetching snapshot metadata... done.
Fetching snapshot generated at Thu Oct 31 20:00:43 EDT 2013:
98c3a00130d24348ff5bcca8474e4c6cb777d838e8f5d2 27% of   69 MB 3728 kBps 00m21s

The portsnap tool will download a snapshot of the tree from the mirror closest to you, verify its integrity against a public key and then extract everything to /usr/ports. You only need to do "fetch extract" the very first time you install. After that, you can keep your tree up to date by issuing:

# portsnap fetch update

For more information and options, see the portsnap man page. It can also be called via a cron script so your tree is updated automatically every night. Specific options can be configured in /etc/portsnap.conf.

Once you have /usr/ports populated with all the makefiles and patches, you're ready to begin installing whatever you need. We'll go through a few basic tasks you might want to do, but first..

As of the time of this writing, there are two package formats you can use: the legacy pkg_add format and the newer pkgng format. For versions of FreeBSD before 10.0, you will need to run the following before installing any ports:

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

That file plays a key role in using ports; you can add lots of customization options to it. An example from one of my systems, with extra comments:

# Build all ports' -march against my cpu for best performance
# Use clang instead of gcc, only needed for versions before 10.0
# Compile everything in a ram disk and use ccache, see our tutorial
# The newer pkgng format, only needed for versions before 10.0
# Use passive FTP and only use IPv4
# Add a fast mirror for downloading distfiles
# Try downloading from it by default
# Strip out some options I'll never want enabled
               APIDOCS NLS

You don't need a make.conf to use ports, but I would encourage you to read up on some of the options before you start building. Flexibility is one of the best parts of building software from source.

The ports system uses a list of "make targets" in order to know what to do. Some common examples include "fetch," "configure," "patch," "install," "clean," "config," "package" and "deinstall." You don't need to memorize all of them, since ports is smart enough to know what to do and in what order. To install an application, you change to that application's directory and do the following:

# cd /usr/ports/www/firefox
# make config-recursive install clean

Now I'll explain what each of those words after "make" means. They're the previously-mentioned targets. You can combine them into one line, or you can run something like:

# make config-recursive
# make
# make install
# make clean

But obviously it's less typing to combine them into one command. The "config-recursive" option will allow you to configure all the options you want the application built with. It also does the same for all of the dependencies of that application. You can enable and disable options through a nice curses-based menu system. If you need to change the options you built a port with, just run "make config" in that port's directory. Just "make" by itself will download the source code, extract it, patch it and build it. The "install" target does exactly that, creates a binary package for the port from the code you compiled and installs it. All ports' installation bits are included in the ports database, specifically in /var/db/ports and /var/db/pkg. The "clean" target will remove anything that was left over from the build. It's there to free up disk space.

To remove a package you installed, you can run:

# cd /usr/ports/www/firefox
# make deinstall

Or use:

# pkg delete firefox

Installing hundreds of programs like this can get a bit tiring, so there are tools you can use to ease the administration. A very popular example is ports-mgmt/portmaster. It's a shell script that can be used for installing and upgrading ports. You can install multiple ports with one command with it and do lots of other great tricks. Check the portmaster page for more info. The portmaster tool is actually a port itself!

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

Installing ports with it is very easy.

# portmaster security/tor irc/irssi sysutils/tmux

You might be interested in the "-d" and "--no-confirm" flags to make it a little less verbose about asking questions. See the above-linked page for more options, or just run "man portmaster."


Keeping things up to date is very important. Updating ports in FreeBSD is a three-step process. The first is to update your ports collection.

# portsnap fetch update

The second is to check for any big changes that need workarounds. There's a special file, /usr/ports/UPDATING, that documents any special steps that need to be taken before upgrading ports. It's recommended that you check it regularly. Each new entry is prepended to the top of the list, so you only need to check the entries since the last time you read it.

# less /usr/ports/UPDATING

Finally, to get a list of any ports that need to be upgraded, run the following:

# pkg version -vIL=

A good site to check for port updates is You can also subscribe to the mailing list. To upgrade all ports (after checking UPDATING, of course) you can tell portmaster to do it with:

# portmaster -ad

You can also just run portmaster on the specific ports that are listed as being outdated to save a bit of time.

# portmaster firefox

When a port is already installed, you don't need to specify the category it's under. That's only when installing them for the first time. It will prompt you if any new options were added to the port since you installed it (with a small "+" next to that option), but use your previously-selected options if there's nothing new.

Some links for further reading:

Latest News

New announcement


We understand that Michael Dexter, Brad Davis, and George Rosamond think there should be more real news....

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 276: ho, ho, ho - 12.0


Direct Download:MP3 AudioVideo Headlines FreeBSD 12.0 is available After a long release cycle, the wait is over: FreeBSD 12.0 is now officially available. We’ve picked a few interesting things to cover in the show, make sure to read the full Release Notes > Userland: > Group permissions on /dev/acpi have been changed to allow users in...

Episode 275: OpenBSD in stereo


Direct Download:MP3 AudioVideo Headlines DragonflyBSD 5.4 released DragonFly version 5.4 brings a new system compiler in GCC 8, improved NUMA support, a large of number network and virtual machine driver updates, and updates to video support. This release is 64-bit only, as with previous releases. The details of all commits...

Episode 274: Language: Assembly


Direct Download:MP3 AudioVideo Headlines Assembly language on OpenBSD amd64+arm64 This is a short introduction to assembly language programming on OpenBSD/amd64+arm64. Because of security features in the kernel, I have had to rethink a series of tutorials covering Aarch64 assembly language on OpenBSD, and therefore this will serve as a placeholder-cum-reminder....

Episode 273: A thoughtful episode


Direct Download:MP3 AudioVideo Headlines Some thoughts on NetBSD 8.0 NetBSD is a highly portable operating system which can be run on dozens of different hardware architectures. The operating system's clean and minimal design allow it to be run in all sorts of environments, ranging from embedded devices, to servers, to workstations....