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

The MacPorts Project uses a system called Trac to file tickets to report bugs and enhancement requests. Though anyone may search Trac for tickets, you must have a GitHub account in order to login to Trac to create tickets.

  • Clean and try again

    If a build fails or is otherwise interrupted, and you try again, MacPorts tries to pick up where it left off. Sometimes this causes new problems, and even if it doesn't, it means that log messages from earlier steps, which can be essential for figuring out why a build failed, are not included in the new log; MacPorts prints Skipping completed in the log for each previously-completed phase that was skipped. Before filing a ticket, sudo port clean the port that failed, then try again.

  • Check the problem hotlist

    The Problem Hotlist contains possible solutions to problems that affect many MacPorts users. If a solution to your problem listed there works, don't file a ticket.

  • Search to see if a Trac ticket has already been filed

    Avoid filing duplicate bugs. Search for duplicates by:

  • Is the problem an application error and not related to compiling and installing?

    In general, application bugs should be reported to the developers of the app (upstream), not MacPorts. An application bug that affects a large number of MacPorts users might merit a MacPorts bug for informational purposes only, but this should be done sparingly.

  • Is the problem with a 'port upgrade' operation?

    If so, try a 'port uninstall foo' and then reinstall. You might also want to run 'port -nR upgrade --force foo' to rebuild ports depending upon port foo. Note that it is safest and recommended that most users always upgrade with 'port upgrade outdated' to update all ports at once. Upgrading a single port can lead to software errors in other ports that have not yet been upgraded.

Once you are logged into Trac, you may click New Ticket and you will be presented with a new ticket window shown in the graphic below. Follow the Trac ticket guidelines below to fill out the form. If you are reporting a failed port install and a log was mentioned in the error, please use the I have files to attach to this ticket checkbox to add that log file to the ticket.

screenshot of a new ticket on the Trac system

This is a short overview of the guidelines for Trac tickets. Please see below for longer and more detailed explanations.



$port $version [$variants]: short problem summary

Example: openssl @1.0.1e_1+universal: DTLS handshake error messages with openconnect

Description Describe your problem. Preformatted text (such as terminal output) should be put in {{{three curly brackets}}}. Please attach large amounts of output rather than pasting. Use the preview button!
defectBugs, build failures, documentation fixes
enhancementImproving existing work
updateUpdate requests or patch submissions for ports
submissionsSubmission of new Portfiles
requestRequests for new ports
Priority Use normal or low. High is reserved for MacPorts developers.
MilestoneLeave empty.
baseTickets affecting MacPorts itself
guideUse for documentation
portsTickets affecting specific ports. Remember to set the port field!
server/hostingUse for infrastructure issues
websiteEnhancements and fixes for the web site
wikiEnhancements and fixes for the wiki (or just edit it directly!)
VersionThe version of MacPorts you are running.
Keywordsmaintainer if you are the port's maintainer. haspatch if you are attaching a patch. Full list.
PortThe name of the port affected by this ticket. Separate multiple using spaces. Leave empty for non-port tickets.
Owner/CcFull email address or GitHub username of the port's maintainer. Run port info --maintainer <portname> to look this up. Do not add or . For ports with multiple maintainers, only put the first maintainer into the Owner field and all others in the Cc field. You do not need to Cc yourself.

There are certain conventions used to ensure that Trac tickets convey as much accurate information as possible so problems and contributions may be acted upon efficiently.

  • Summary: [port] [version] [concise description]

    • Example: "rrdtool @1.2.23 +python Configure error - build failure"

  • Description: All details that might be relevant to someone reading the ticket. Be sure to mention the versions of your operating system and Xcode install. Wiki formatting should be used to ensure that text is formatted correctly. Use the Preview button before submitting. If you want to post preformatted text such as a log or terminal output, make sure you use {{{...}}} around the text or it could break the page layout. Example:

    your error message here

    Submitters are advised to trim inline pastes and logs to what's really relevant to the report, as otherwise overly large ticket pages can become unmanageable. Long output, such as the full log from a port build, should be added as an attachment, not pasted inline. See I have files to attach to this ticket below.

  • Type: There are five types of tickets.

    • defect - The default; any port/MacPorts build/runtime failures and/or documentation corrections.

    • enhancement - Tickets, with or without patches, created to enhance something that isn't failing its intended purpose.

    • update - Tickets, with or without patches, involving updating a port to a newer upstream version.

    • submission - Tickets created to submit Portfiles for software not currently available in MacPorts.

    • request - Tickets created to request the creation of a new port.

  • Priority: Assign a priority level to the ticket.

    • High - Reserved for the use of MacPorts team members, as they are the best fit to determine which reports warrant a higher priority over others.

    • Normal - The default. For normal port failures, non-critical enhancement requests, non-critical port failures.

    • Low - For mostly cosmetic improvements, documentation corrections/improvements, etc.

    • Not set - Anything that doesn't fit the categories high, normal, or low.

  • Milestone: Leave this blank. MacPorts developers will set this to the version of MacPorts that contains a fix for the ticket when they commit a change. Note that this is only meaningful for changes in MacPorts itself, since changes to ports are continuously provided to users. If the milestone is MacPorts Future no version of MacPorts with the fix has been released yet.

  • Component: Set what part of the MacPorts Project the ticket is to be filed against.

    • base - Tickets related to MacPorts base code.

    • guide - Documentation enhancements and error corrections, or patches to the MacPorts Guide.

    • ports - Tickets related to ports.

    • server/hosting - For MacPorts hosting & server-side issues.

    • website - MacPorts website enhancements and error corrections.

    • wiki - MacPorts Wiki enhancements and error corrections.

  • Version: Select the MacPorts version you are using when it is applicable.

  • Keywords: Type any keywords that might help when searching for tickets. It is not useful to list words here that already appear elsewhere in the ticket. Keywords also serve as tags; for example, use tiger if reporting a bug that only affects OS X 10.4, haspatch if a fix is attached to the ticket, maintainer if you are the port's maintainer, or LP64 if reporting an issue that only affects 64-bit platforms.

    See the TicketsKeywordGuidelines wiki page for a clickable list of all keywords.

  • Cc: Anyone else besides the ticket reporter and assignee who would like to be kept involved in the development of the ticket. Multiple email addresses or GitHub usernames should be separated with a comma and a space (e.g., neverpanic, you@example.org, maintainer@macports.org).

    When reporting port-related tickets, make sure you add the port maintainers email address or GitHub username to the Cc: field so they are notified of the ticket (unless you have commit access, then see Assign To: below). You can obtain the email address or GitHub username of the port maintainer by running port info --maintainers [port]

  • Assign To: Only users with commit access can edit this field. If this is not you, see the section on the Cc field above.

    For tickets on ports, enter the email address or GitHub username of the port's maintainer (use port info [port] to find this). If multiple maintainers are listed, enter the first maintainer's email address or GitHub username here and enter the remaining maintainers' email addresses or GitHub usernames in the Cc field. Exclude the email address if it appears. If the maintainer's email address is , leave the field blank.

  • Port: For tickets on ports, enter the name of the port (or ports, space-separated, when multiple are affected).

  • I have files to attach to this ticket: Use this checkbox to attach files to the ticket immediately after you create it. Or you can attach files later using the Attach File button.

    If the file you are attaching is larger than 256 KiB, please compress it with bzip2 or gzip first to save space on the server and bandwidth for those downloading it, as Trac will not preview files above that size anyway.