FreeBSD offers two primary methods of downloading applications and system tools: packages and ports. Users will have to choose between the two collections when installing these tools. Packages are pre-compiled binary packages, typically smaller in size than full port installations and they do not require compilation time. However, ports are a much more customizable option, allowing users to directly interact with the build process and configure the application to their preference. Additionally, installing an application from a port can help a user understand how the application is compiled, configured, and finally built into a binary. It can be a very rewarding process!

For this guide, we will be compiling irssi, a powerful and modular text-based Internet Relay Chat (IRC) client, from the Ports Collection.

NOTE: ensure that you run all the following commands as the root user by running $ sudo su once.


Before we start, ensure you have a working installation of FreeBSD. If you do not, you can follow these installation walkthroughs:

Once you have FreeBSD installed, start up your machine and boot into FreeBSD. If you installed FreeBSD or a similar variant (e.g. PC-BSD, TrueOS, etc.), powering your machine on will automatically boot into the operating system. 

To do this on VirtualBox, open the application, select your FreeBSD machine, and click “Start”:

You’ll see a FreeBSD boot menu pop up: let it automatically boot and bring you to the login screen.

Then, after logging in, you should see a welcome screen and a shell prompt appear similar to this:

You are now ready to get started!

1. Setup the Ports Collection:

To begin installing ports on our FreeBSD system, we must first download the Ports Collection. The following command will download the latest compressed snapshot of the Ports Collection and extract it into the /usr/ports directory:

$ portsnap fetch extract

Later on, if we want to update our snapshot of the Ports Collection, we can run:

$ portsnap fetch update

2. Navigating the Ports Collection

Now that the Ports Collection has been installed, we need to be able to find applications that we want to install on our system. The Ports Collection contains directories for software categories, and inside each category are subdirectories for individual applications. We will determine the relevant information necessary to navigate to the irssi port.

  • Visit the official FreeBSD ports website and click on “Listed by Logical Group” in the sidebar on the left. Here, we can browse the list of applications available as ports in each category. We can also search for applications using the highlighted search bar.

  • Search for irssi and take note of the category and package name of the application from the results page.

  • Navigate to the application’s directory in the Ports Collection, substituting in the category name and package name you noted earlier:


In our example, the category name is “irc” and the package name is “irssi”, so you would type:

$ cd /usr/ports/irc/irssi

3. Installing the Port

Now that we are inside the directory for the irssi port, we can begin understanding the installation process. This application directory, called the port skeleton, contains a set of files that tells FreeBSD how to compile and install the program. Each port skeleton includes these files and directories:

  • Makefile: contains statements that specify how the application should be compiled and where its components should be installed.
  • distinfo: contains the names and checksums of the files that must be downloaded to build the port.
  • files/: this directory contains any patches needed for the program to compile and install on FreeBSD. This directory may also contain other files used to build the port.
  • pkg-descr: provides a more detailed description of the program.
  • pkg-plist: a list of all the files that will be installed by the port. It also tells the ports system which files to remove upon deinstallation.

NOTE: The port does not include the actual source code, also known as a distfile. The “extract” portion the build process will automatically download and save the compressed source code in the /usr/ports/distfiles directory.

To install the port (and clean the directory to remove any temporary files afterward), type

$ make install clean

Notice that a screen similar to the following will show up:

This is a good example of one of the benefits of compiling irssi from the Ports Collection! It allows you to precisely configure which additional features you want to bundle with the final application binary. Some defaults are already chosen for us, but let’s add “truecolor” support in case we want full bit-depth color when using irssi in a compatible terminal emulator. Navigate to the option using the arrow keys and press “<Space>”. Once you are satisfied with the configuration, navigate to the “OK” option and press “<Enter>”.

4. Running the application

You now have irssi installed on your system! Before running it, we’ll do a few things first:

  • Exit your root user session by typing $ exit
  • Ensure that irssi has been successfully added to your PATH by typing:

$ which irssi

  •  The expected output is /usr/local/bin/irssi.

To run the application, simply type $ irssi. You should see a screen like this:

For further information on how to use irssi, type in /help in the “status” line. Now you’ll be able to chat with people over IRC!

You did it!

As you can see, compiling and installing an application from the Ports Collection is a satisfying process. However, we just scratched the surface of this process, so for more information, check out the following links:

BONUS:  The Ports Collection includes games too! Try using this guide to install 2048, a clone of the popular 2048 game implemented with a command-line interface. This is a great way to explore all the options available for fine-tuning your application build process.