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

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

EuroBSDCon 2014


As you might expect, both Allan and Kris will be at EuroBSDCon this year. They'll be busy hunting down various BSD developers and forcing them to do interviews, but don't hesitate to say hi if you're a listener!...

BSDCan 2014


We just wrapped up episode 35 after having some horrible audio issues. Sorry about the quality being lower than usual, we did the best we could given the circumstances. Next week we've got a normal episode, but the following week Allan and Kris will be at BSDCan. That week will...

AsiaBSDCon 2014


Both Allan and Kris will be going to AsiaBSDCon this year, so episode 28 will be shorter than usual. We'll be back the following week with a huge episode. Hopefully they can get some interviews there!...

Christmas & New Year


Episode 16 was just uploaded, and that's the last one we'll be doing live for this year. Episode 17 will be on Christmas, and feature a prerecorded interview with Scott Long about his BSD magic over at Netflix. Thanks for watching everyone! We look forward to more BSD Now in...

Episode 056: Beastly Infrastructure


Direct Download: Video | HD Video | MP3 Audio | OGG Audio | Torrent This episode was brought to you by Interview - Peter Wemm - / @karinjiri The FreeBSD web cluster and infrastructure Feedback/Questions Todd writes in Brandon writes in All the tutorials are posted in their entirety at Send questions, comments, show ideas/topics, or stories...

Episode 055: The Promised WLAN


Direct Download: Video | HD Video | MP3 Audio | OGG Audio | Torrent This episode was brought to you by Headlines FreeBSD 10.1-BETA1 is out The first maintenance update in the 10.x series of FreeBSD is on its way Since we can't see a changelog yet, the 10-STABLE release notes offer a glimpse at some...

Episode 054: Luminary Environment


Direct Download: Video | HD Video | MP3 Audio | OGG Audio | Torrent This episode was brought to you by Headlines Portscout ported to OpenBSD Portscout is a popular utility used in the FreeBSD ports infrastructure It lets port maintainers know when there's a new version of the upstream software available by automatically checking the...

Episode 053: It's HAMMER Time


Direct Download: Video | HD Video | MP3 Audio | OGG Audio | Torrent This episode was brought to you by Headlines FreeBSD foundation's new IPSEC project The FreeBSD foundation, along with Netgate, is sponsoring some new work on the IPSEC code With bandwidth in the 10-40 gigabit per second range, the IPSEC stack needs to...