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 & Useful Tcl Commands
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. Updating Documentation
7.5. MacPorts Membership
7.6. The PortMgr Team
8. MacPorts Guide Terms
Glossary

This section lists common operations you may want to perform when managing a MacPorts installation. These are the workflows you will need most while using MacPorts. We recommend you read at least this section as a primer into how to use MacPorts. More details about the usage can be found in Section 3.1, “The port Command” and the port(1) manpage available by running man 1 port in a Terminal.

Mind the sudo for some of the subsequent examples, which is necessary if you have a default MacPorts installation.

The local ports tree is a collection of files that contain information on which packages are available through MacPorts and how they can be installed. You should regularly update your ports tree to get access to updated versions of software and bug fixes. To do that, use selfupdate:

$ sudo port selfupdate
Password:
---> Updating MacPorts base sources using rsync
MacPorts base version 2.4.1 installed,
MacPorts base version 2.4.1 downloaded.
---> Updating the ports tree
---> MacPorts base is already the latest version

The ports tree has been updated. To upgrade your installed ports, you should run
  port upgrade outdated

To see what's new after running selfupdate, you can use port outdated to generate a list of ports that have newer versions available. This can help in estimating the time required for sudo port upgrade outdated, even though this depends on further factors such as binary package availability and a port's build time.

$ port outdated
The following installed ports are outdated:
gnupg                          1.4.16_0 < 1.4.18_0
gnupg2                         2.0.22_2 < 2.0.25_0
gpg-agent                      2.0.22_1 < 2.0.25_0
gpgme                          1.5.0_0 < 1.5.1_0
HexFiend                       2.1.2_1 < 2.3.0_0
libksba                        1.0.8_0 < 1.3.0_0
p5.16-class-methodmaker        2.180.0_1 < 2.210.0_0
p5.16-gnupg-interface          0.330.0_3 < 0.500.0_1
p5.16-ipc-run                  0.910.0_1 < 0.920.0_0

To upgrade all your installed and outdated ports, run

$ sudo port upgrade outdated

In case you want to upgrade only a specific port (not recommended unless you know what you are doing), replace outdated in the command given above with the port's name:

$ sudo port upgrade makedepend
Password:
---> Computing dependencies for makedepend
---> Fetching makedepend
---> Attempting to fetch makedepend-1.0.3.tar.bz2 from http://lil.fr.distfiles.macports.org/makedepend
---> Verifying checksum(s) for makedepend
---> Extracting makedepend
---> Configuring makedepend
---> Building makedepend
---> Staging makedepend into destroot
---> Computing dependencies for makedepend
---> Installing makedepend @1.0.3_0
---> Deactivating makedepend @1.0.2_0
---> Activating makedepend @1.0.3_0
---> Cleaning makedepend

Note that MacPorts will upgrade any dependencies of a port first before updating the port itself. So even if you request the update of a single port only, other ports may be upgraded first because they are in the dependency tree. Do not try to avoid this, as it will very likely lead to problems later on – the new version of the port you want to upgrade might require the newer dependency, or it might only have been upgraded at all to be rebuilt against the updated dependency, in which case avoiding the update of the dependency defeats the purpose of the reinstallation.

By default, upgrading ports in MacPorts does not remove the older versions. This is a safety measure to ensure you can go back to a working and tested version in case an update goes wrong. To save disk space, you should periodically uninstall any old versions you no longer need.

Use

$ port installed inactive

to get a list of inactive ports you likely no longer need.

The following ports are currently installed:
  gnupg @1.4.16_0
  gnupg2 @2.0.22_2
  gpg-agent @2.0.22_1
  gpgme @1.5.0_0
  HexFiend @2.1.2_1
  libksba @1.0.8_0
  p5.16-class-methodmaker @2.180.0_1
  p5.16-gnupg-interface @0.330.0_3
  p5.16-ipc-run @0.910.0_1

Check the list for any ports you might still want to keep. To remove all of them at once, run

$ sudo port uninstall inactive
Password:
--->  Uninstalling p5.16-gnupg-interface @0.330.0_3
--->  Cleaning p5.16-gnupg-interface
--->  Uninstalling gnupg @1.4.16_0
--->  Cleaning gnupg
--->  Uninstalling gpgme @1.5.0_0
--->  Cleaning gpgme
--->  Uninstalling gnupg2 @2.0.22_2
--->  Cleaning gnupg2
--->  Uninstalling gpg-agent @2.0.22_1
--->  Cleaning gpg-agent
--->  Uninstalling HexFiend @2.1.2_1
--->  Cleaning HexFiend
--->  Uninstalling libksba @1.0.8_0
--->  Cleaning libksba
--->  Uninstalling p5.16-class-methodmaker @2.180.0_1
--->  Cleaning p5.16-class-methodmaker
--->  Uninstalling p5.16-ipc-run @0.910.0_1
--->  Cleaning p5.16-ipc-run

Of course you could also select only a specific inactive port, but that requires to specify the exact version:

$ sudo port uninstall HexFiend @2.1.2_1
Password:
--->  Uninstalling HexFiend @2.1.2_1
--->  Cleaning HexFiend

To uninstall all inactive ports but a single one, you can use the following shortcut:

$ sudo port uninstall inactive and not <portname>

If you want to find all ports that depend on a given other port, you can use

$ port echo depends:<portname>

If you are only interested in the dependent ports that you actually have installed, you can use the quicker and more accurate dependents:

$ port dependents <portname>
$ port dependents libksba
gnupg2 depends on libksba
gpg-agent depends on libksba

MacPorts also has a recursive version of the dependents action called rdependents:

$ port rdependents libksba
The following ports are dependent on libksba:
  gnupg2
    gpgme
  gpg-agent

Finally, to find out which port you manually installed caused the automatic installation of a dependency, use the following expression:

$ port installed requested and rdependentof:<portname>
$ port installed requested and rdependentof:libksba
The following ports are currently installed:
  gnupg2 @2.0.25_0 (active)

After a while of using MacPorts, installing and uninstalling ports, packages that have been automatically installed as dependencies for other ports are left behind, even though they are no longer necessary. Ports that have not been manually installed (requested) and do not have any dependents are called leaves and can be identified using the leaves pseudo-port, for example in conjunction with the echo or installed action.

$ port echo leaves
git-flow                       @0.4.1_2
gmake                          @4.0_0
gpgme                          @1.5.1_0
hs-download-curl               @0.1.4_0
pkgconfig                      @0.28_0
py27-docutils                  @0.12_0
python32                       @3.2.5_0
texi2html                      @5.0_1
yasm                           @1.2.0_0

These leaves may be wanted, but are in most cases unneeded. See Section 3.3.7, “Keep Your Installation Lean by Defining Leaves as Requested Ports” to find out how to mark some of the leaves as requested. You can uninstall all leaves using

$ sudo port uninstall leaves

Note that the uninstallation can cause new ports to become leaves. To uninstall all leaves, you would have to repeat the process until port echo leaves comes back empty. To automate this, you can use --follow-dependencies when uninstalling.

$ sudo port uninstall --follow-dependencies leaves

To go through this process interactively so you can make sure you're not uninstalling anything you want to keep, you can install the port_cutleaves port. After installation, run it with

$ sudo port_cutleaves

Well, before we come to the procedure of defining your requested ports, let's have a look at a typical scenario where you want to understand what is actually installed and what is on the other hand truly necessary for your system. Say checking leaves of your MacPorts installation gives this output:

$ port echo leaves
git-flow                       @0.4.1_2
gmake                          @4.0_0
gpgme                          @1.5.1_0
hs-download-curl               @0.1.4_0
pkgconfig                      @0.28_0
py27-docutils                  @0.12_0
python32                       @3.2.5_0
texi2html                      @5.0_1
yasm                           @1.2.0_0

Now it is up to the user to decide what's needed and what is not. We've noticed pkgconfig is needed to build many ports, and while it is strictly not needed after installation, we'd like to keep it around to avoid installing it over and over again. python32, texi2html, and yasm are only needed to update mplayer2, and since that software is rarely updated, we will re-install those ports again when they are needed. Since they are all distributable, MacPorts will use pre-built binaries for their installation anyway, so re-installing them wouldn't take long anyway. We don't really know why the rest of the leaves were installed, so we're just going to remove them for now.

Since we decided to keep pkgconfig, we are going to mark it as manually installed (requested in MacPorts lingo) using:

$ sudo port setrequested pkgconfig

When you've step-by-step figured out which ports you want to keep on your system and have set them as requested, you'll have a list of unnecessary ports, which you can get rid of using

$ sudo port uninstall leaves

Note that uninstalling leaves may mark new ports as leaves, so you will have to repeat the process. You can install the port_cutleaves port, which is a special script for the job. It allows you to interactively decide whether to keep or uninstall a port. Run it as

$ sudo port_cutleaves
[Leaf 1 of 8] hs-download-curl @0.1.4_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort:
** hs-download-curl @0.1.4_0 will be kept.

[Leaf 2 of 8] gmake @4.0_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** gmake @4.0_0 will be uninstalled.

[Leaf 3 of 8] texi2html @5.0_1 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** texi2html @5.0_1 will be uninstalled.

[Leaf 4 of 8] yasm @1.2.0_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** yasm @1.2.0_0 will be uninstalled.

[Leaf 5 of 8] python32 @3.2.5_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** python32 @3.2.5_0 will be uninstalled.

[Leaf 6 of 8] py27-docutils @0.12_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** py27-docutils @0.12_0 will be uninstalled.

[Leaf 7 of 8] git-flow @0.4.1_2 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** git-flow @0.4.1_2 will be uninstalled.

[Leaf 8 of 8] gpgme @1.5.1_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** gpgme @1.5.1_0 will be uninstalled.

--->  Deactivating gmake @4.0_0
--->  Cleaning gmake
--->  Uninstalling gmake @4.0_0
--->  Cleaning gmake
--->  Deactivating texi2html @5.0_1
--->  Cleaning texi2html
--->  Uninstalling texi2html @5.0_1
--->  Cleaning texi2html
--->  Deactivating yasm @1.2.0_0
--->  Cleaning yasm
--->  Uninstalling yasm @1.2.0_0
--->  Cleaning yasm
--->  Deactivating python32 @3.2.5_0
--->  Cleaning python32
--->  Uninstalling python32 @3.2.5_0
--->  Cleaning python32
--->  Deactivating py27-docutils @0.12_0
--->  Cleaning py27-docutils
--->  Uninstalling py27-docutils @0.12_0
--->  Cleaning py27-docutils
--->  Deactivating git-flow @0.4.1_2
--->  Cleaning git-flow
--->  Uninstalling git-flow @0.4.1_2
--->  Cleaning git-flow
--->  Deactivating gpgme @1.5.1_0
--->  Cleaning gpgme
--->  Uninstalling gpgme @1.5.1_0
--->  Cleaning gpgme

The following ports were uninstalled:
  gmake @4.0_0
  texi2html @5.0_1
  yasm @1.2.0_0
  python32 @3.2.5_0
  py27-docutils @0.12_0
  git-flow @0.4.1_2
  gpgme @1.5.1_0

Search for new leaves?
  [no] / (y)es: y

[Leaf 1 of 1] py27-roman @2.0.0_0 (active):
  [keep] / (u)ninstall / (f)lush / (a)bort: u
** py27-roman @2.0.0_0 will be uninstalled.

--->  Deactivating py27-roman @2.0.0_0
--->  Cleaning py27-roman
--->  Uninstalling py27-roman @2.0.0_0
--->  Cleaning py27-roman

The following ports were uninstalled:
  py27-roman @2.0.0_0

Search for new leaves?
  [no] / (y)es: y

There are no new leaves to process.

You can get a list of all ports you previously set as requested (or installed manually) using:

$ port installed requested

We recommend you check the list of leaves from time to time to keep your system free of too much garbage. You should also periodically check the list of your requested ports and mark any ports you no longer need as unrequested using

$ sudo port unsetrequested <portname>

Then check for new leaves to cut down the number of installed ports and the size of your MacPorts installation.