1. Introduction
2. Installing MacPorts
2.1. Install Xcode
2.2. Install MacPorts
2.3. MacPorts Upgrade
2.4. Uninstall
2.5. MacPorts and the Shell
3. Using MacPorts
3.1. The port Command
3.2. Port Variants
3.3. Common Tasks
3.4. Port Binaries
4. Portfile Development
4.1. Portfile Introduction
4.2. Creating a Portfile
4.3. Example Portfiles
4.4. Port Variants
4.5. Patch Files
4.6. Local Portfile Repositories
4.7. Portfile Best Practices
4.8. MacPorts' buildbot
5. Portfile Reference
5.1. Global Keywords
5.2. Global Variables
5.3. Port Phases
5.4. Dependencies
5.5. Variants
5.6. Tcl Extensions
5.7. StartupItems
5.8. Livecheck / Distcheck
5.9. PortGroups
6. MacPorts Internals
6.1. File Hierarchy
6.2. Configuration Files
6.3. Port Images
6.4. APIs and Libs
6.5. The MacPorts Registry
7. MacPorts Project
7.1. Using Trac for tickets
7.2. Contributing to MacPorts
7.3. Port Update Policies
7.4. MacPorts Membership
7.5. The PortMgr Team
8. MacPorts Guide Terms

This chapter describes using the port command, port variants, common tasks and port binaries.

The MacPorts port command is the main utility used to interact with MacPorts. It is used to update Portfiles and the MacPorts infrastructure, and install and manage ports.

The help action shows some brief information about the specified action, or if no action is specified, shows basic usage information for the port command in general.

%% port help selfupdate
Usage: selfupdate --nosync

Upgrade MacPorts itself and run the sync target

The selfupdate action should be used regularly to sync the local ports tree with the global MacPorts ports repository so you will have the latest port versions. It also checks for new revisions of the MacPorts infrastructure, called MacPorts base, and upgrades it when necessary.


Selfupdate is only tested on OS X. If you are running MacPorts on another platform, selfupdate may not work correctly. In this case, you should use the sync action to update the ports tree; to update MacPorts base you must manually install a newer version from source.

%% sudo port selfupdate
--->  Updating MacPorts base sources using rsync
MacPorts base version 2.3.1 installed,
MacPorts base version 2.3.1 downloaded.
--->  Updating the ports tree
--->  MacPorts base is already the latest version

As always, you can use the debug flag for verbose output. This is useful to debug problems with selfupdate.

%% sudo port -d selfupdate

If selfupdate detects that a newer version of MacPorts base is available, it automatically updates the installed copy of MacPorts base to the latest released version. In that case, you will see this message:

--->  Updating MacPorts base sources using rsync
MacPorts base version 2.3.0 installed,
MacPorts base version 2.3.1 downloaded.
--->  Updating the ports tree
--->  MacPorts base is outdated, installing new version 2.3.1
Installing new MacPorts release in /opt/local as root:admin; permissions 755

If the selfupdate procedure fails you'll see a message like this:

Error installing new MacPorts base: command execution failed

Re-run selfupdate with the -d flag to see all output generated by the build system. The output may give you an idea why the build failed. If it doesn't, please file a ticket and attach the output generated by sudo port -d selfupdate.

The sync action performs a subset of selfupdate actions. It synchronizes the ports tree, as does selfupdate, but it does not check for upgrades to MacPorts base. On OS X, unless there is a special reason not to do so, you should run selfupdate.


For platforms other than OS X, sync is the only way to get port updates because selfupdate is supported only on OS X.

The list action lists the currently available version of the specified ports, or if no ports are specified, displays a list of all available ports. The list of available ports is very long, so use search if you know a port's name or part of it.

%% port list

The search action allows finding ports by partial matches of the name or description. Other fields can be matched against, and matched in different ways, by using options. Run port help search for details.

%% port search rrd
php5-rrdtool @1.0 (php, net, devel)
    PHP 5 glue for rrdtool

rrdtool @1.4.4 (net)
    Round Robin Database

Found 2 ports.

The info action is used to get information about a port: description, maintainer, etc.

%% port info flowd
flowd @0.9 (net)
Variants:             universal

Description:          flowd is a small, fast and secure NetFlow collector.
Homepage:             http://www.mindrot.org/flowd.html

Platforms:            darwin
License:              unknown
Maintainers:          nomaintainer@macports.org

The deps action shows you the dependencies of a port; dependencies are explicitly declared in Portfiles.

%% port deps apache2
Full Name: apache2 @2.2.17_0+preforkmpm
Library Dependencies: apr, apr-util, expat, openssl, pcre

The variants action allows you to check what variations of a port are available before you install it. Variants are a way for port authors to provide options that may be invoked at install time. See Invoking Port Variants below to install ports that have variants.

%% port variants nmap
nmap has the variants:
   no_pcre: build without pcre support
   no_ssl: build without ssl support
   universal: Build for multiple architectures
   zenmap: build zenmap in addition to nmap

The action install is used to install a port. See Invoking Port Variants below to install ports that have variants.

%% sudo port install nmap


You may break up a port's installation into smaller steps for troubleshooting by passing port a prior installation phase such as fetch, configure, build, or destroot. See section Port Phases for a complete list of phases.

The action clean deletes all intermediate files that MacPorts creates while building a port. A port clean is also often necessary to remove corrupted tarballs after a failed fetch phase.

%% sudo port clean --all vile


You may also clean files selectively by using options --dist, --archive, or --work.

The uninstall action will remove an installed port.

%% sudo port uninstall vile


To also recursively uninstall the ports that the given port depends on, use the ‑‑follow‑dependencies flag. This will not uninstall dependencies that are marked as requested or that have other dependents.

%% sudo port uninstall --follow-dependencies vile

To recursively uninstall all ports that depend on the given port before uninstalling the port itself, use the ‑‑follow‑dependents flag.

%% sudo port uninstall --follow-dependents ncurses

If a port is a dependency of another installed port, uninstall will not remove it unless you remove the dependent port(s) first. To override this behavior, use the -f (force) switch. This will obviously break the dependents. Don't force uninstall ports unless you know what you are doing.

%% sudo port -f uninstall ncurses

The contents action displays the files that have been installed by a given port. Uninstalled ports cannot have their contents listed.

%% port contents xorg-renderproto
Port xorg-renderproto contains:

The installed action displays the installed versions, variants and activation status of the specified ports, or if no ports are specified, all installed ports. Use the -v option to also display the platform and CPU architecture(s) for which the ports were built, and any variants which were explicitly negated.

%% port installed
The following ports are currently installed:
  aalib @1.4rc5_2 (active)
  apr @1.2.8_0 (active)
  apr-util @1.2.8_2 (active)
  atk @1.18.0_0 (active)

[ ... trimmed ...]

  wxWidgets @2.8.4_2 (active)
  Xft2 @2.1.7_0 (active)
  xrender @0.9.0_0 (active)
  zlib @1.2.3_1 (active)
%% port -v installed atlas
The following ports are currently installed:
  atlas @3.8.3_4+gcc44-gcc43 (active) platform='darwin 10' archs='x86_64'

The outdated action checks your installed ports against the current ports tree to see if updated Portfiles have been released since your ports were installed. Note that you will not see new versions unless you have updated your ports tree using selfupdate or sync.

%% port outdated
apr                            1.2.8_0 < 1.2.9_0
autoconf                       2.61_0 < 2.61_1
gimp                           2.2.14_0 < 2.2.16_0
libtool                        1.5.22_0 < 1.5.24_0
pkgconfig                      0.21_0 < 0.22_0

The upgrade action upgrades installed ports and their dependencies when a Portfile in the repository has been updated after a port was installed.

%% sudo port upgrade gnome

If you wish not to upgrade a port's dependencies, use the -n switch. Note that this will often cause problems.

%% sudo port -n upgrade gnome

If you'd like to upgrade all outdated ports, use this command.

%% sudo port upgrade outdated


The upgrade action by default does not uninstall an upgraded port —it deactivates it. See section Port Images, and also Destroot and Activate phases in Port Phases. If you wish to uninstall the old version, use the -u option.

%% sudo port -u upgrade vile

The dependents action reports what ports depend upon a given port, if any. MacPorts learns about dependents during port installation, so uninstalled ports will always report that there are no dependents.

%% port dependents openssl
neon depends on openssl
gnome-vfs depends on openssl
libdap depends on openssl

The livecheck action checks to see if the application corresponding to a given port has been updated at the developer's download site. It's especially useful for port maintainers, but others may also wish to see if a port has the latest available distribution source. See section Livecheck for more information.

%% port livecheck rrdtool
rrdtool seems to have been updated (port version: 1.2.23, new version: 1.3beta1)


If livecheck finds no higher version at the port's download site, it prints nothing. The option -d (debug) may be used for detailed livecheck processing information.

The lint action checks if the Portfile conforms to the MacPorts standards specified in Portfile Development.

If a Portfile validates fine the following message is shown.

%% port lint chemtool
--->  Verifying Portfile for chemtool
--->  0 errors and 0 warnings found.

Otherwise the warnings and errors are listed.

%% port lint KeyArcher
--->  Verifying Portfile for KeyArcher
Warning: Line 2 should be a newline (after RCS tag)
Warning: Line 5 has trailing whitespace before newline
Error: Missing required variable: platforms
--->  1 errors and 2 warnings found.