1. Introduction
2. Installing MacPorts
2.1. Install Xcode
2.2. Install MacPorts
2.3. Upgrade MacPorts
2.4. Uninstall MacPorts
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
6.6. Tests
7. MacPorts Project
7.1. Using Trac for Tickets
7.2. Using Git and GitHub
7.3. Contributing to MacPorts
7.4. Port Update Policies
7.5. Updating Documentation
7.6. MacPorts Membership
7.7. The PortMgr Team
8. MacPorts Guide Glossary

6.2. Configuration Files

The MacPorts configuration files often do not need to be modified for the general end user. They contain options that may be of use to advanced users and port developers. Some automatically configured options may need to be updated when migrating to a new CPU architecture or a new OS version.

There are three MacPorts configuration files that define important variables used by the MacPorts system: macports.conf, sources.conf, and variants.conf. All MacPorts configurations files are located in ${prefix}/etc/macports.

MacPorts configuration file format is a simple key/value pair separated by either a space or a tab. Lines beginning with '#' are comments, empty lines are ignored.

6.2.1. macports.conf

macports.conf is the configuration file used to bootstrap the MacPorts system. This file is read by the port command and determines how it behaves.

Options locating other .conf files.


Where to find the sources list.

Default: ${prefix}/etc/macports/sources.conf


Where to find global variants definition file (optional).

Default: ${prefix}/etc/macports/variants.conf

Options for MacPorts general operating characteristics.


Sets the directory where ports are installed. Any path may be used but those with spaces and/or non-ASCII characters should be avoided because it can break some ports.

Default: /opt/local


Directory where MacPorts keeps working data such as downloaded sources, installed port receipts, and the main registry. Same path restrictions apply as for '${prefix}'.

Default: ${prefix}/var/macports


Formerly selected the storage type to use for the MacPorts registry: flat or sqlite. Currently, only sqlite can be used.

Default: sqlite


The machine architecture for which to build in normal use. Options include: arm64, i386, ppc, ppc64, x86_64


(Snow Leopard and later) arm64, x86_64 or i386 depending on hardware

(Leopard/Tiger) i386 or ppc depending on hardware


Directory in which ports will install native macOS application bundles.

Default: /Applications/MacPorts


Directory in which ports will install native macOS frameworks.

Default: ${prefix}/Library/Frameworks


Directory where Xcode is installed.

Default: /Developer


Controls whether ports are built from source or downloaded as pre-built archives. Setting to 'always' will never use archives, 'never' will always try to use an archive and fail if one is not available. 'ifneeded' will try to fetch an archive and fall back to building from source if that isn't possible.

Default: ifneeded


Format of archives in which to store port images. This controls both the type of archive created locally after building from source, and the type to request from remote servers. Changing this will not affect the usability of already installed archives; they can be of any supported type. Supported types are: tgz, tar, tbz, tbz2, tlz, txz, xar, zip, cpgz, cpio

Default: tbz2


Use ccache (C/C++ compiler cache) - see https://ccache.samba.org/

Default: no


Use distcc (distributed compiler) - see https://distcc.samba.org/

Default: no


Use pipes rather than intermediate files when compiling C/C++/etc

Default: yes


Lowered scheduling priority (0-20) to use for make when building ports.

Default: 0


Number of simultaneous make jobs (commands) to use when building ports. Using 0 will cause a runtime autodetection to use all available processor cores.

Default: 0


Set whether to automatically execute clean after install of ports.

Default: yes


Rsync server from which to fetch MacPorts sources.

Default: rsync.macports.org


Rsync directory from which to pull the base/ component (infrastructure) of MacPorts.

Default: release/tarballs/base.tar


Rsync options

Default: -rtzv --delete-after


Umask value to use during the destrooting of a port.

Default: 022


Sets env(PATH), the directory search path for locating system executables (rsync, tar, etc.) during port installation. Only applications in these directories are available while ports are being installed even if other paths are specified by $PATH in a user's environment.

Default: ${prefix}/bin:${prefix}/sbin:/bin:/sbin:/usr/bin:/usr/sbin


The binpath is implicitly defined, but it may be overwritten by defining the variable in macports.conf. However, using a non-default binpath is discouraged and should only be performed by advanced users.


Space-separated list of download hosts that should not be used.

Default: none


This feature is especially useful if a host turns out to be consistently slow and therefore should be excluded for MacPorts' actions.


Space-separated list of download hosts that should be used preferentially.

Default: none


Controls whether the rev-upgrade action will be run automatically after upgrading ports.

Default: yes


Controls the rev-upgrade functionality which checks for broken linking and can rebuild ports to fix it. 'rebuild' means ports will automatically be rebuilt when broken linking is detected in their files, while 'report' means broken files will be scanned for and reported but the ports will not be rebuilt.

Default: rebuild

Options for MacPorts Universal Binaries (+universal variant)


The machine architectures to use for +universal variant (multiple entries must be space delimited). Options include: arm64, i386, ppc, ppc64, x86_64

Default: arm64 x86_64 for macOS 11 and later, x86_64 i386 for 10.6 through 10.13, ppc i386 for 10.5 and earlier

Options for StartupItems


Options for generated startup items, though this may be overridden by the startupitem.type Portfile key. Options are default option, SystemStarter, launchd, or none. For an empty or default option, a startupitem type appropriate to the platform is used; if none, no port startupitems are installed.

Default: default


Create system-level symlinks to generated StartupItems. If set to no, symlinks will not be created; otherwise, symlinks will be placed in /Library/LaunchDaemons or /Library/LaunchAgents as appropriate. This setting only applies when building ports from source.

Default: yes

Other options


Extra environment variables to keep. Any variables listed here are added to the list of variables that are not removed from the environment used while processing ports.

Default: none


Set whether to place a symlink named work from your ports tree to the build directory of a port, when the port is being built. This is convenient, but may not be ideal if you care about the structure of your ports tree. For example, some developers keep their ports tree synchronized across multiple computers, and don't want to also synch build directories.

Default: yes

6.2.2. sources.conf

This file enables rsync synchronization of the default ports tree with the MacPorts rsync server when either of the commands port selfupdate or port sync are run.

Default: rsync://rsync.macports.org/macports/release/tarballs/ports.tar [default]

Optional local repositories are enabled using a file url: file:///path/to/localportsrepository

6.2.3. variants.conf

This optional file specifies any variants you'd like to be invoked globally. If a variant specified in this file is not supported by a given Portfile, the variant is simply ignored.

Default: none