Overview

This guide is designed to help provide you with a quick start to using MacPorts. It will cover installing, updating, and removing open source software from your computer provided via the MacPorts infrastructure, in addition to some other important basics.

It is important to understand that MacPorts is designed so that all software installed within MacPorts is installed to its own self-contained directory (/opt/local, by default). Software can be built into this directory without interfering with any Apple-provided services or Mac OS X in general.

This guide was originally written by Joe Auty and published on ​NetMusician.

Adding MacPorts to your Terminal's path

You can interact with MacPorts either using a GUI, or using the Terminal. If you choose to use the Terminal, the Terminal needs to know to look in your MacPorts directory (i.e. /opt/local if you are using the defaults) to find its utilities. If you installed MacPorts using the InstallingMacPorts page then you should be able to open a Terminal window and type:

port version

If you get a "command not found" error then your path isn't set right and you must review InstallingMacPorts.

Selfupdate

The basic syntax for using MacPorts is:

port <command-name>

where "command-name" is one of the commands, or "actions" that MacPorts recognizes. For a list of all MacPorts actions, type in man port in your Terminal to read the man page for a complete reference guide to the Port command. We will touch on some important ones here, starting with "selfupdate".

Selfupdate is the command used to automatically download new Portfiles so that your local copy of MacPorts is aware of new MacPorts software or upgrades to existing software that have been committed to the MacPorts infrastructure. Additionally, this command is used to update the MacPorts software itself - think of it is a Software Update, like its name suggests.

After installing MacPorts, try running a selfupdate to grab all the latest MacPorts Portfiles (Portfiles contain information about how to install MacPorts software "ports"). You will need to run this command as an administrator, and it requires root access, so you'll need to "sudo":

sudo port selfupdate

Running MacPorts commands, you can add the -v command for more verbose ("v" for "verbose") output if you'd like more detail about what MacPorts is attempting to do:

sudo port -v selfupdate

If you are a developer and would like even more specific accounting of what MacPorts is doing, add the -d flag.

Searching for ports

To find out what software is available within the MacPorts infrastructure, you can view our Available Ports page, the GitHub ​source browser directly or run a quick search using MacPorts itself. For instance, if you wanted to search for the VIM editor:

port search vim

This will output a list of results where each item looks as the following:

vim @7.3.21 (editors)
    Vi "workalike" with many additional features

For more info on a port:

port info vim

Variants

You may notice that info on several ports provides a list of Variants. You can also produce this same list using the "variants" action:

port variants vim

Variants are options that can be built into your install of the port. If you have ever compiled software by hand, you'll know that these options can be set via configure script arguments (e.g. ./configure --prefix=/opt/local). It can be confusing to figure out what each variant enables, but if you are confused you can send a question to one of the MacPorts mailing lists. The variants for vim include specifying a feature set (+huge, +big, +small or +tiny) or different languages for scripting (+perl, +python26, +python27, +ruby, etc.).

Installing ports

To install vim without extra features, just use this command:

sudo port install vim

To install vim with support for python 2.6 and the huge feature set, issue the following command:

sudo port install vim +python26 +huge

This command will download, compile, and install the vim port from the vim website with the specified build options. Since it will take a while to build and install several ports, you might want to include the -v flag so that you have evidence that the build is in progress:

sudo port -v install vim +python26 +huge

You may notice that MacPorts will build software that you didn't specifically request. This will occur if the port you originally requested has other ports marked as dependencies. Even if the software already exists without OS X, remember the whole MacPorts self-contained design approach. Some recreation of existing software may be necessary to produce a functional self-contained environment.

Verifying your install

After the build and install is complete, if there were no problems along the way, your port should be added to your port registry. For a complete list of all installed ports:

port installed

If you are not seeing your port listed, chances are there were some errors in the install. Please share any error messages you encountered with the MacPorts mailing list so that we can commit corrections.

Upgrading existing ports

To list all outdated ports, quickly running a selfupdate will make sure that your list of outdated ports reflects the latest versions available within the MacPorts infrastructure. To run a selfupdate:

sudo port -v selfupdate

To list all outdated ports:

port outdated

To upgrade a particular port:

sudo port upgrade <portname>

where command name is the name of the port as listed in the "port outdated" list.

To upgrade all outdated ports:

sudo port upgrade outdated

(You can add the "-v" flag following "port" in the above commands if you'd like to watch the compiler output.)

What if my port install/upgrade fails?

Regardless of whether you include the verbose flag, if there is an error it will be provided. Please file a ticket in MacPorts' Trac ticketing system and assign it to the port maintainer listed in the Portfile or send a message to the MacPorts mailing lists.

How do I configure my MacPorts installed application and start it up for the first time?

Many configuration files for non-Aqua software will be located in /opt/local/etc. If applicable to your port, you will need to edit your config file in this location in preparation for use. If your config file ends in a suffix containing something like "sample", you may need to copy it to exclude this suffix. The general approach of providing a "template" config file ensures that the config file you have setup will not be overwritten the next time you upgrade your port. In fact, all ports should be designed not to blow away your configuration. If this isn't the case, please contact the port maintainer or send an email to the list.

You will need to consult the documentation for the software you have installed to find out how to manually start and stop it if it includes a daemon that is necessary to be running in order for the software to work.

How do I set my MacPorts installed software to automatically startup at boot?

Software that includes a daemon that needs to run in order for the software to work often include a variant to install the hooks necessary for the daemon to automatically start at boot time. In versions of Mac OS X older than and including 10.3.x, when the appropriate variant is specified the SystemStarter script will be installed. In versions newer than and including 10.4.x, a launchd item will be installed. Please check your SystemStarter or launchctl man pages to learn how to manually invoke these startup scripts so that you can test the starting/stopping of your software without having to reboot your machine. In some cases, using SystemStarter/Launchd may be the only way to manually start/stop the daemon(s).

If your MacPorts installed software is intended to replace an Apple-provided service, you should disable it to prevent conflicts. There are several techniques you can use to replace various Apple-provided bits. Please contact the list for further information.

How do I know when an update is available? Do I have to constantly perform manual checks?

Selfupdate is a command that can safely be scheduled to automatically run, as it doesn't actually update your installed software, it just "teaches" MacPorts about new updates. Take a look at using crontabs to run your selfupdate. You will probably have to provide the full path to the "port" command in your crontab, i.e.:

/opt/local/bin/port selfupdate

You will need to set this crontab for the root user, as normal users cannot perform selfupdates.

You can also run "port outdated" as a scheduled task. By enabling the Postfix mail transport agent (a number of guides and utilities are available in OS X for doing so - this is a very easy task), the output of your crontab jobs will be emailed to you. Creating crontabs for both selfupdates and generating outdated port lists can be very useful in learning about new updates on a regular basis.

HOWTOs

We also maintain a HOWTO section in this wiki. It contains several guides and solutions which might be useful for you.

Help!

Please see the Contact Us! page for further information on how to get in contact with the MacPorts team.