The Ports Collection is a set of
Makefiles, patches, and description files.
Each set of these files is used to compile and install an individual
application on FreeBSD, and is called a port.
By default, the Ports Collection itself is stored as a subdirectory
Before an application can be compiled using a port, the Ports Collection must first be installed. If it was not installed during the installation of FreeBSD, use one of the following methods to install it:
The base system of FreeBSD includes Portsnap. This is a fast and user-friendly tool for retrieving the Ports Collection and is the recommended choice for most users. This utility connects to a FreeBSD site, verifies the secure key, and downloads a new copy of the Ports Collection. The key is used to verify the integrity of all downloaded files.
To download a compressed snapshot of the Ports Collection into
When running Portsnap for the first time, extract the snapshot into
After the first use of Portsnap has been completed as shown above,
/usr/portscan be updated as needed by running:
updateoperation may be run consecutively, like so:
portsnap fetch update
If more control over the ports tree is needed or if local changes need to be maintained, Subversion can be used to obtain the Ports Collection. Refer to the Subversion Primer for a detailed description of Subversion.
Subversion must be installed before it can be used to check out the ports tree. If a copy of the ports tree is already present, install Subversion like this:
make install clean
If the ports tree is not available, or pkg is being used to manage packages, Subversion can be installed as a package:
pkg install subversion
Check out a copy of the ports tree:
svn checkout https://svn.FreeBSD.org/ports/head /usr/ports
As needed, update
/usr/portsafter the initial Subversion checkout:
svn update /usr/ports
The Ports Collection contains directories for software categories. Inside each category are subdirectories for individual applications. Each application subdirectory contains a set of files that tells FreeBSD how to compile and install that program, called a ports skeleton. 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.
Some ports include
other files to handle special situations. For more details
on these files, and on ports in general, refer to the FreeBSD
The port does not include the actual source code, also
known as a
distfile. The extract portion
of building a port will automatically save the downloaded
This section provides basic instructions on using the
Ports Collection to install or remove software. The detailed
description of available
make targets and
environment variables is available in ports(7).
Before compiling any port, be sure to update the Ports
Collection as described in the previous section. Since
the installation of any third-party software can introduce
security vulnerabilities, it is recommended to first check
for known security issues related to the port. Alternately,
pkg audit -F before installing a new
port. This command can be configured to automatically
perform a security audit and an update of the vulnerability
database during the daily security system check. For more
information, refer to pkg-audit(8) and
Using the Ports Collection assumes a working Internet connection. It also requires superuser privilege.
To compile and install the port, change to the directory
of the port to be installed, then type
install at the prompt. Messages will indicate
make install>> lsof_4.88D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/. >> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/. ===> Extracting for lsof-4.88 ... [extraction output snipped] ... >> Checksum OK for lsof_4.88D.freebsd.tar.gz. ===> Patching for lsof-4.88.d,8 ===> Applying FreeBSD patches for lsof-4.88.d,8 ===> Configuring for lsof-4.88.d,8 ... [configure output snipped] ... ===> Building for lsof-4.88.d,8 ... [compilation output snipped] ... ===> Installing for lsof-4.88.d,8 ... [installation output snipped] ... ===> Generating temporary packing list ===> Compressing manual pages for lsof-4.88.d,8 ===> Registering installation for lsof-4.88.d,8 ===> SECURITY NOTE: This port has installed the following binaries which execute with increased privileges. /usr/local/sbin/lsof
lsof is a program that runs
with increased privileges, a security warning is displayed
as it is installed. Once the installation is complete, the
prompt will be returned.
Some shells keep a cache of the commands that are
available in the directories listed in the
PATH environment variable, to speed up lookup
operations for the executable file of these commands. Users
tcsh shell should type
rehash so that a newly installed command
can be used without specifying its full path. Use
hash -r instead for the
sh shell. Refer to the documentation
for the shell for more information.
During installation, a working subdirectory is created which contains all the temporary files used during compilation. Removing this directory saves disk space and minimizes the chance of problems later when upgrading to the newer version of the port:
make clean===> Cleaning for lsof-88.d,8
To save this extra step, instead use
install clean when compiling the port.
Some ports provide build options which can be used to
enable or disable application components, provide security
options, or allow for other customizations. Examples
If the port depends upon other ports which have configurable
options, it may pause several times for user interaction
as the default behavior is to prompt the user to select
options from a menu. To avoid this and do all of the configuration
in one batch, run
within the port skeleton. Then, run
install [clean] to compile and install the
config-recursive, the list of
ports to configure are gathered by the
all-depends-list target. It is
recommended to run
config-recursive until all dependent ports
options have been defined, and ports options screens no
longer appear, to be certain that all dependency options
have been configured.
There are several ways to revisit a port's build options
menu in order to add, remove, or change these options after
a port has been built. One method is to
cd into the directory containing the
port and type
make config. Another
option is to use
Another option is to execute
rmconfig which will remove all selected options
and allow you to start over. All of these options, and
others, are explained in great detail in
The ports system uses fetch(1) to download the
source files, which supports various environment variables.
variables may need to be set if the FreeBSD system is behind
a firewall or FTP/HTTP proxy. See fetch(3) for the
complete list of supported variables.
For users who cannot be connected to the Internet all
make fetch can be run within
/usr/ports, to fetch all distfiles, or
within a category, such as
/usr/ports/net, or within the specific
port skeleton. Note that if a port has any dependencies,
running this command in a category or ports skeleton will
not fetch the distfiles of ports from
another category. Instead, use
fetch-recursive to also fetch the distfiles for
all the dependencies of a port.
In rare cases, such as when an organization has a local
distfiles repository, the
variable can be used to override the download locations
specified in the
Makefile. When using,
specify the alternate location:
make MASTER_SITE_OVERRIDE= \
PREFIX variables can override the default
working and target directories. For example:
make WRKDIRPREFIX=/usr/home/example/ports install
will compile the port in
/usr/home/example/ports and install
make PREFIX=/usr/home/example/local install
will compile the port in
and install it in
make WRKDIRPREFIX=../ports PREFIX=../local install
will combine the two.
These can also be set as environmental variables. Refer to the manual page for your shell for instructions on how to set an environmental variable.
Installed ports can be uninstalled using
delete. Examples for using this command can be
found in the pkg-delete(8) manual page.
make deinstall can be
run in the port's directory:
make deinstall===> Deinstalling for sysutils/lsof ===> Deinstalling Deinstallation has been requested for the following 1 packages: lsof-4.88.d,8 The deinstallation will free 229 kB [1/1] Deleting lsof-4.88.d,8... done
It is recommended to read the messages as the port is uninstalled. If the port has any applications that depend upon it, this information will be displayed but the uninstallation will proceed. In such cases, it may be better to reinstall the application in order to prevent broken dependencies.
Over time, newer versions of software become available in the Ports Collection. This section describes how to determine which software can be upgraded and how to perform the upgrade.
To determine if newer versions of installed ports are available, ensure that the latest version of the ports tree is installed, using the updating command described in either Procedure4.1, “Portsnap Method” or Procedure4.2, “Subversion Method”. On FreeBSD 10 and later, or if the system has been converted to pkg, the following command will list the installed ports which are out of date:
pkg version -l "<"
For FreeBSD 9.
X and lower, the
following command will list the installed ports that are out
pkg_version -l "<"
attempting an upgrade, read
/usr/ports/UPDATING from the top of
the file to the date closest to the last time ports were
upgraded or the system was installed. This file describes
various issues and additional steps users may encounter and
need to perform when updating a port, including such things
as file format changes, changes in locations of
configuration files, or any incompatibilities with previous
versions. Make note of any instructions which match any of
the ports that need upgrading and follow these instructions
when performing the upgrade.
The Ports Collection contains several utilities to perform the actual upgrade. Each has its strengths and weaknesses.
Historically, most installations used either Portmaster or Portupgrade. Synth is a newer alternative.
The choice of which tool is best for a particular system is up to the system administrator. It is recommended practice to back up your data before using any of these tools.
ports-mgmt/portmaster is a very small utility for upgrading installed ports. It is designed to use the tools installed with the FreeBSD base system without depending on other ports or databases. To install this utility as a port:
make install clean
Portmaster defines four categories of ports:
Root port: has no dependencies and is not a dependency of any other ports.
Trunk port: has no dependencies, but other ports depend upon it.
Branch port: has dependencies and other ports depend upon it.
Leaf port: has dependencies but no other ports depend upon it.
To list these categories and search for updates:
portmaster -L===>>> Root ports (No dependencies, not depended on) ===>>> ispell-3.2.06_18 ===>>> screen-4.0.3 ===>>> New version available: screen-4.0.3_1 ===>>> tcpflow-0.21_1 ===>>> 7 root ports ... ===>>> Branch ports (Have dependencies, are depended on) ===>>> apache22-2.2.3 ===>>> New version available: apache22-2.2.8 ... ===>>> Leaf ports (Have dependencies, not depended on) ===>>> automake-1.9.6_2 ===>>> bash-3.1.17 ===>>> New version available: bash-3.2.33 ... ===>>> 32 leaf ports ===>>> 137 total installed ports ===>>> 83 have new versions available
This command is used to upgrade all outdated ports:
By default, Portmaster
makes a backup package before deleting the existing port.
If the installation of the new version is successful,
Portmaster deletes the
Portmaster not to automatically
delete the backup. Adding
Portmaster in interactive mode,
prompting for confirmation before upgrading each port.
Many other options are available. Read through the
manual page for portmaster(8) for details regarding
If errors are encountered during the upgrade process,
-f to upgrade and rebuild all
Portmaster can also be used to install new ports on the system, upgrading all dependencies before building and installing the new port. To use this function, specify the location of the port in the Ports Collection:
More information about ports-mgmt/portmaster
may be found in its
ports-mgmt/portupgrade is another utility that can be used to upgrade ports. It installs a suite of applications which can be used to manage ports. However, it is dependent upon Ruby. To install the port:
make install clean
Before performing an upgrade using this utility, it is
recommended to scan the list of installed ports using
pkgdb -F and to fix all the
inconsistencies it reports.
To upgrade all the outdated ports installed on the
portupgrade -a. Alternately,
-i to be asked for confirmation
of every individual upgrade:
To upgrade only a specified application instead of all
available ports, use
. It is very
important to include
-R to first upgrade
all the ports required by the given application:
portupgrade -R firefox
-P is included,
Portupgrade searches for
available packages in the local directories listed in
PKG_PATH. If none are available locally, it
then fetches packages from a remote site. If packages can
not be found locally or fetched remotely,
Portupgrade will use ports. To
avoid using ports entirely, specify
This last set of options tells
Portupgrade to abort if no
packages are available:
portupgrade -PP gnome3
To just fetch the port distfiles, or packages, if
-P is specified, without building or
installing anything, use
-F. For further
information on all of the available switches, refer to the
manual page for
More information about ports-mgmt/portupgrade
may be found in its
Using the Ports Collection will use up disk space over
time. After building and installing a port, running
make clean within the ports skeleton will
clean up the temporary
If Portmaster is used to install a
port, it will automatically remove this directory unless
-K is specified. If
Portupgrade is installed, this
command will remove all
found within the local copy of the Ports Collection:
In addition, outdated source distribution files
time. To use Portupgrade to
delete all the distfiles that are no longer
referenced by any ports:
Portupgrade can remove all distfiles not referenced by any port currently installed on the system:
If Portmaster is installed, use:
By default, this command is interactive and prompts the user to confirm if a distfile should be deleted.
In addition to these commands, ports-mgmt/pkg_cutleaves automates the task of removing installed ports that are no longer needed.