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

You may contribute new ports and enhancements of any kind to already existing ports using Trac tickets. As an alternative, you may instead open a pull request on GitHub, in which case no Trac ticket is required.

Ports are contributed by following these steps. See the Ticket Submission Guidelines for a description of all fields.

  1. Please run

    %% port lint --nitpick $portname

    where $portname is the name of the port you are submitting. Please fix any warnings and errors.

  2. Either create a Trac ticket ...

    1. Set the type to submission.

    2. Set the component to ports.

    3. Set the port field to the name of the new port.

    4. Attach the Portfile and any required patchfiles to the ticket.

  3. ... or submit the port update through a pull request on GitHub.

  4. If your ticket or pull request doesn't receive any attention within a few days you may send an email to and request a review and/or commit. Please include a link to the ticket or pull request.

Enhancements to existing ports may comprise new functionality for a given port, bug fixes or even simple version updates. They should always be contributed as patches against the current Portfile. See the Ticket Submission Guidelines for a description of all fields.

  1. Create a Portfile patch with your changes. See Portfile Development for more information on how to edit Portfiles.

  2. Please run

    %% port lint --nitpick $portname

    where $portname is the name of the port you modified. Please fix any warnings and errors before submitting your changes.

  3. Either create a Trac ticket ...

    1. Set the type to enhancement for miscellaneous enhancements, to defect for bug fixes, or to update for version updates.

    2. Set the component to ports.

    3. Set the port field to the name of the port you want to change.

    4. Put the maintainer's email address or GitHub username into the Cc field. You can use

      %% port info --maintainer $portname

      where $portname is the name of the port you want to modify. Note that and are not real people and should thus not be Cc'd.

    5. Attach your Portfile patch file and any new or changed patch files to the ticket.

  4. ... or submit the new port through a pull request on GitHub.

  5. If your ticket or pull request doesn't receive any attention within a few days you may send an email to and request a review and/or commit. Please include a link to the ticket or pull request.

MacPorts is always looking for people that want to take care of a certain package. If you notice an outdated port, a bug in a port or simply a port without maintainer that you are interested in, feel free to volunteer as maintainer. To become a maintainer you need:

  • An email address or a GitHub account.

  • A copy of the Portfile. Do not worry if you don't know where to find one yet. There's more documentation on that below.

  • An account in the MacPorts Trac, preferably with the email address you want to use for your port.

  • Interest in the software you want to maintain and some time.

You do not need:

  • Commit access to the MacPorts repository. Instead, you create patches and open tickets in Trac. You can, however, apply for commit access once you have some experience in maintaining ports. In fact, we would like to encourage you to apply after a few months.

  • Expert knowledge of the software you want to maintain or experience in Portfile programming. You can pick those up along the way. Your knowledge about the software you want to maintain is probably more than what most other MacPorts developers have, given the number of ports MacPorts has. Consult Chapter 4, Portfile Development chapter and Chapter 5, Portfile Reference on how to write a Portfile. If your questions are not answered there, please ask on the mailing list.

To become the maintainer of a port, first check whether the port already has a maintainer. Run

%% port info --maintainer $portname

where $portname is the name of the port you want to maintain. If the output is

maintainer: 

the port is unmaintained and you are more than welcome to take it over. If the output lists a different email address, you can still co-maintain the port, but you should contact the existing maintainer(s) first.

Once you have verified that a port is unmaintained or the existing maintainer has invited you to co-maintain the port of your choice, follow these steps to become a maintainer:

  1. Locate the port's directory and make a copy. MacPorts can help you locate the directory that contains the Portfile by running port dir $portname. Copy this directory to a separate location (so you can easily generate a patch later) that is readable by the macports user. In general, your home directory does not fulfill that requirement, but /var/tmp does.

    %% cp -r $(port dir $portname) /var/tmp

    Check /var/tmp for the new directory. In most cases, its name should be equal to the name of the port you want to maintain. In those few cases where it is not (i.e., the so-called subports feature is used), check the output of port dir $portname for the correct name.

  2. Change to the new directory and run port info to make sure everything went right. Note that running any port command without a port name tries to use the Portfile in the current directory. This is very helpful when testing modifications or new ports, so keep this in mind.

    %% cd /var/tmp/$portname
    %% port info

    If you don't see info output for the port, but an error message instead, it will usually be in the following form:

    Can't map the URL 'file://.' to a port description file ("couldn't read file "Portfile": permission denied").
    Please verify that the directory and portfile syntax are correct.
    To use the current port, you must be in a port's directory.

    Pay attention to the part in the brackets in the first line. It will either contain a permission problem (in which case you need to adjust the permissions of your Portfile and the folders leading up to it), or a Tcl error message, in case of syntax errors in the Portfile. Also check that the copy of the working directory is in fact the current working directory in your shell.

  3. Open the Portfile in your favorite editor and look for the line that starts with maintainer. Delete nomaintainer from the line if it exists and add your own GitHub username or email address. For GitHub usernames, prefix your username with an @ sign. Email addresses should be written in the form domain.tld:localpart. The address is obfuscated to prevent email harvesters from automatically grabbing your address. If you want, you can start fixing bugs in the Portfile as well.

    At this point, please read Section 7.3.1, “Non-Maintainer Port Updates” and familiarize yourself with the meaning of openmaintainer. Consider adding openmaintainer to speed up and simplify small updates of your port. If you decided to allow minor updates without consultation, add openmaintainer, separated with a space, to the maintainer line of the Portfile.

    Once you are done, save the file and verify the Portfile structure using MacPorts' builtin lint check:

    %% port lint --nitpick

    You will likely see at least one error:

    Error: Portfile parent directory tmp does not match primary category $XYZ

    You can safely ignore this message. It is printed because the copy of the port's directory is not in a directory named after the port's primary category, but in /var/tmp instead. Please try to address all other warnings and error messages, though. If you need help, feel free to continue and add a note to the ticket you will create asking for instructions.

    Finally, run port info again. The maintainers line in the output should now contain your email address or GitHub username.

    Note

    If you made changes other than the maintainer line, you might want to test build and installation as well. To do that, run sudo port destroot in the port's directory. If you see

    Error: Unable to execute port: Could not open file: /private/var/tmp/somewhere/Portfile

    check the permissions of the Portfile and all folders above it. They must be readable by the macports user. The easiest way to ensure this is to run

    %% chmod -R go+rX /var/tmp/$portname

    If the port fails to build, see the main.log referenced in the error message for details. If the build completes successfully, run sudo port clean to clean up all leftovers.

  4. Create a patch from the changes you made to the Portfile and possible related files. To do that, run

    %% diff -uR $(port dir $portname) . > change-$portname-maintainer.diff

    in the directory where you edited the Portfile. You can inspect the generated unified diff in change-$portname-maintainer.diff if you want.

  5. If you are only changing the maintainer, file a new ticket in Trac. Set type to enhancement. Leave the milestone field empty. If you added yourself as co-maintainer, add the other maintainers in the Cc field. Finally, fill in the port field, set keywords to haspatch (because you are attaching a patch), check the box that you want to attach files to the ticket and submit. After submission, attach the patch you created in the previous step.

    If you are also fixing a bug, attach a separate patch for that change to the same ticket. If you are fixing a bug that already has a ticket, attach a patch fixing the bug there and file the maintainer change in a separate ticket (with a separate patch) as discussed above. In general, please create a separate patch for each semantic change. Doing so simplifies reviewing. It enables each independent change to be accepted without worries about conflicts that sometimes arise when several changes are rolled into one patch. Do not worry that you cannot change the keywords to haspatch on existing tickets.

  6. If your ticket doesn't receive any attention within a few days you may send an email to and request a review and/or commit. Please include a link to the ticket.

Once you are the maintainer for a port, all new tickets for this port will be assigned to you. You are expected to take a look at these tickets, give advice and try to debug problems. If you are stuck, do not hesitate to ask on the list.