Introduction

MacPorts is an easy to use system for compiling, installing, and managing open source software. MacPorts may be conceptually divided into two main parts: the infrastructure, known as MacPorts base, and the set of available ports.

A MacPorts port is a set of specifications contained in a Portfile that defines an application, its characteristics, and any files or special instructions required to install it. This allows you to use a single command to tell MacPorts to automatically download, compile, and install applications and libraries. But using MacPorts to manage your open source software provides several other significant advantages.

For example, MacPorts:

Installs automatically any required support software, known as dependencies, for a given port.
Provides for uninstalls and upgrades for installed ports.
Confines ported software to a private “sandbox” that keeps it from intermingling with your operating system and its vendor-supplied software to prevent them from becoming corrupted.
Allows you to create pre-compiled binary installers of ported applications to quickly install software on remote computers without compiling from source code.

MacPorts is developed on macOS, though it is designed to be portable so it can work on other Unix-like systems, especially those descended from the Berkeley Software Distribution (BSD). In practice, installing ports only works on macOS. MacPorts base can be compiled on Linux (and possibly other POSIX-compatible systems) where it is mainly used to set up mirrors and generate support files for installations on macOS.

The following notational conventions are used in the MacPorts Guide to distinguish between terminal input/output, file text, and other special text types.

Terminal I/O and file text:

Commands to be typed into a terminal window.

Command output to a terminal window.

File text.

Other special text types:
- A hyperlink: spontaneous combustion.
- A file: /var/log/system.log.
- A command: ifconfig.
- An option: port install.

Installing Macports

This chapter shows you how to install MacPorts and its prerequisites step-by-step. Note that the section about installing Xcode is macOS-specific. If you wish to install MacPorts on another platform, first make sure you have a working C compiler installed, skip ahead to installing MacPorts from source, and continue to the end of the chapter.

Install Xcode

Xcode is a package provided by Apple containing compilers, libraries and additional tools required to develop applications for macOS.

Always make sure to install the latest available version of Xcode for your macOS release; using outdated versions of Xcode may cause port install failures. Also note that Xcode is not updated via OS X’s Software Update utility on OS versions prior to 10.6, and is updated via the Mac App Store starting with 10.7.

Follow the instructions for your version of macOS:

Install Xcode on OS X 10.9 or Later

Download the latest version of Xcode from the Apple developer website or get it using the Mac App Store.

Once you have Xcode installed, open a terminal, run xcode-select --install, and click the Install button to install the required command line developer tools. Don’t worry if you see a message telling you the software cannot be installed because it is not currently available from the Software Update Server. This usually means you already have the latest version installed. You can also get the command line tools from the Apple developer website.

Install Xcode on OS X 10.7 Lion or OS X 10.8 Mountain Lion

Download the latest version of Xcode from the Apple developer website or get it using the Mac App Store.

Xcode 4.3 and later do not automatically install the command line tools, but MacPorts requires them. To install them, open the Xcode application, go to the Preferences window, to the Downloads section, and click the Install button next to Command Line Tools. Be sure to return to this window after every Xcode upgrade to ensure that the command line tools are also upgraded.

If you wish to create Installer packages with port pkg, you will also need to install PackageMaker, which is in the “Auxiliary Tools for Xcode” package as of Xcode 4.3. The download page for this package can be opened via the Xcode -> Open Developer Tool -> More Developer Tools… menu item. After downloading and mounting the disk image, drag the PackageMaker application to your /Application directory.

Install Xcode on Mac OS X 10.6 Snow Leopard

If you are using Mac OS X 10.6, there are two branches of Xcode which could be considered to be the latest, 3.2.x and 4.x. Xcode 4 costs money, but Xcode 3 is still available free of charge. There are two options for downloading it:

Xcode 3.2 - smaller download, but you will need to run Software Update after installing to get the latest version. Note that Apple might at some point discontinue providing these updates via their update servers.
Xcode 3.2.6 and iOS SDK 4.3 - includes the iOS SDK which is not needed for MacPorts.

Both are available from the Apple developer website. You may also be able to install Xcode 3.2 from your Mac OS X 10.6 DVD and then run Software Update to get the latest version.

Ensure that those of the following options that are available in the installer for your version of Xcode are selected:

UNIX Development
System Tools
X11 SDK
Command Line Support

Install Xcode on Older Releases of Mac OS X

If you have an earlier release of Mac OS X, you may download the latest version of Xcode for Mac OS X 10.5 (Xcode 3.0 and Xcode 3.1 Developer Tools) or 10.4 (Xcode 2.4.1 and Xcode 2.5 Developer Tools) from the Apple developer website.

Ensure that those of the following options that are available in the installer for your version of Xcode are selected:

UNIX Development
System Tools
X11 SDK
Command Line Support

Install MacPorts

If you are using macOS, you should install MacPorts using the macOS package installer unless you do not wish to install it to /opt/local/, the default MacPorts location, or if you wish to install a pre-release version of MacPorts base. However, if you wish to install multiple copies of MacPorts or install MacPorts on another OS platform, you must install MacPorts from the source code.

macOS Package Install

The macOS package installer automatically installs MacPorts, sets the shell environment, and runs a selfupdate operation to update the ports tree and MacPorts base with the latest release.

Download the latest MacPorts-2.5.4-....pkg installer from the releases on GitHub. Here are direct links for the latest versions of macOS:
- macOS 10.14 Mojave:
  
  MacPorts-2.5.4-10.14-Mojave.pkg
- macOS 10.13 High Sierra:
  
  MacPorts-2.5.4-10.13-HighSierra.pkg
- macOS 10.12 Sierra:
  
  MacPorts-2.5.4-10.12-Sierra.pkg
Double-click the downloaded package installer to perform the default “easy” install.
After this step you are done already, MacPorts is now installed and your shell environment was set up automatically by the installer. To confirm the installation is working as expected, now try using port in a new terminal window.

port version

Version: 2.5.4

In case of problems such as “command not found”, make sure that you opened a new terminal window or consult Section 2.5, “MacPorts and the Shell”. Otherwise, please skip the remainder of this chapter and continue with Chapter 3, Using MacPorts in this guide.

Source Install

If you installed MacPorts using the package installer, skip this section. To install MacPorts from the source code, follow the steps below.

Download and extract the MacPorts 2.5.4 tarball. Either do so using your browser and the Finder, or use the given commands in a terminal window.
```
curl -O https://distfiles.macports.org/MacPorts/MacPorts-2.5.4.tar.bz2
```
```
tar xf MacPorts-2.5.4.tar.bz2
```
Afterwards, perform the commands shown in the terminal window. If you wish to use a path other than /opt/local, follow the instructions for installing multiple copies of MacPorts instead.
```
cd MacPorts-2.5.4/
```
```
./configure
```
```
make
```
```
sudo make install
```
Please continue with Section 2.5, “MacPorts and the Shell” to set up your shell environment.

Git Install

If you installed MacPorts using the package installer, skip this section.

There are times when some may want to run MacPorts from a version newer than the current stable release. Maybe there’s a new feature that you’d like to use, or it fixes an issue you’ve encountered, or you just like to be on the cutting edge. These steps explain how to setup MacPorts for developers, using only Git to keep MacPorts up to date.

Though a distinction is made between pre-release and release versions of MacPorts base, the ports collection supports no such distinction or versioning. The selfupdate command installs the latest ports tree, and updates MacPorts base to the latest released version.

Check out MacPorts source

Pick a location to store a working copy of the MacPorts code. For this example, /opt/mports will be used, but you can put the source anywhere. This example will create /opt/mports/macports-base containing everything needed for MacPorts.
```
mkdir -p /opt/mports
```
```
cd /opt/mports
```
```
git clone https://github.com/macports/macports-base.git
```
```
git checkout v2.5.4  # skip this if you want to use the development version
```
Build and Install MacPorts

MacPorts uses autoconf and makefiles for installation. These commands will build and install MacPorts to /opt/local. You can add --prefix to ./configure to relocate MacPorts to another directory if needed.
```
cd /opt/mports/macports-base
```
```
./configure --enable-readline
```
```
make
```
```
sudo make install
```
```
make distclean
```
(Optional) Configure MacPorts to use port information from Git

This step is useful if you want to do port development. Check out the ports tree from git:
```
cd /opt/mports
```
```
git clone https://github.com/macports/macports-ports.git
```
Then open /opt/local/etc/macports/sources.conf in a text editor. The last line should look like this:
```
rsync://rsync.macports.org/macports/release/tarballs/ports.tar [default]
```
Change it to point to the working copy you checked out:
```
file:///opt/mports/macports-ports [default]
```
Environment

You should setup your PATH and other environment options according to Section 2.5, “MacPorts and the Shell”.

Install Multiple MacPorts Copies

Occasionally a MacPorts developer may wish to install more than one MacPorts instance on the same host. Only one copy of MacPorts may use the default prefix /opt/local, so for additional installations use the option --prefix as shown below. It’s also recommended to change the applications dir using –with-applications-dir to avoid conflicts in /Applications/MacPorts. Use --without-startupitems to automatically set startupitem_install no in the new macports.conf, which is required to avoid conflicts in /Library/LaunchAgents or /Library/LaunchDaemons.

The first command temporarily removes the standard MacPorts binary paths because they must not be present while installing a second instance.

export PATH=/bin:/sbin:/usr/bin:/usr/sbin

MP_PREFIX=/opt/macports-test

./configure --prefix=$MP_PREFIX --with-applications-dir=$MP_PREFIX/Applications --without-startupitems

make

sudo make install

MacPorts Upgrade

MacPorts base upgrades are performed automatically (when a newer release is available) during a selfupdate operation. To upgrade a copy of MacPorts that was installed from source to the newer release of the source code, simply repeat the source install with the newer version of the MacPorts source code.

Uninstall

Uninstalling MacPorts can be a drastic step, and depending on the issue you are experiencing, you may not need to do so. If you are unsure, ask on the macports-users mailing list first.

If you need to uninstall MacPorts, and port is functioning, first uninstall all the installed ports by running this command in the Terminal:

sudo port -fp uninstall installed

All that will be left in your installation prefix now will be files that were not registered to any port. This includes configuration files, databases, any files which MacPorts renamed in order to allow a forced installation or upgrade, and the base MacPorts software itself. You may wish to save your configuration files (most are in $prefix/etc), databases, or any other unique data by moving it aside.

To remove all remaining traces of MacPorts, run the following command in the Terminal. If you have changed prefix, applications_dir or frameworks_dir from their default values, then replace /opt/local with your prefix, replace /Applications/MacPorts with your applications_dir, and/or add your frameworks_dir to the list, respectively.

sudo rm -rf \
        /opt/local \
        /Applications/DarwinPorts \
        /Applications/MacPorts \
        /Library/LaunchDaemons/org.macports.* \
        /Library/Receipts/DarwinPorts*.pkg \
        /Library/Receipts/MacPorts*.pkg \
        /Library/StartupItems/DarwinPortsStartup \
        /Library/Tcl/darwinports1.0 \
        /Library/Tcl/macports1.0 \
        ~/.macports

If you use a shell other than bash (perhaps tcsh), you may need to adjust the above to fit your shell’s syntax. Also note that depending on which version of MacPorts you have and which ports you have installed, not all of the above paths will exist on your system. This is OK.

MacPorts and the Shell

MacPorts requires that some environment variables be set in the shell. When MacPorts is installed using the macOS package installer, a “postflight” script is run after installation that automatically adds or modifies a shell configuration file in your home directory, ensuring that it defines variables according to the rules described in the following section. Those installing MacPorts from source code must modify their environment manually using the rules as a guide.

Depending on your shell and which configuration files already exist, the installer may use .profile, .bash_login, .bash_profile, .tcshrc, or .cshrc.

The Postflight Script

The postflight script automatically sets the PATH variable, and optionally the MANPATH and DISPLAY variables according to the rules described below. If a current shell configuration file exists at installation time it is renamed to “mpsaved_$timestamp”. Those installing MacPorts from source code must modify their environment manually using the rules as a guide.

Required: PATH variable

This variable is set by the postflight script to prepend the MacPorts executable paths to the current path as shown. This puts the MacPorts paths at the front of PATH so that the MacPorts binaries will take precedence over vendor-supplied binaries.
```
export PATH=/opt/local/bin:/opt/local/sbin:$PATH
```

The user environment’s $PATH is not in effect while ports are being installed, because the $PATH is scrubbed before ports are installed, and restored afterwards. To change the search path for locating system executables (rsync, tar, etc.) during port installation, see the macports.conf file variable binpath. But changing this variable is for advanced users only, and is not generally needed or recommended.

Optional: MANPATH variable

Condition: If prior to MacPorts installation a MANPATH variable exists in a current .profile that contains neither the value ${prefix}/share/man, nor any empty items separated by a colon, the postflight script sets the MANPATH variable as shown below. Otherwise, the MANPATH variable is omitted.
Optional: DISPLAY variable

Condition: If installing on a Mac OS X version earlier than 10.5 (Leopard), and if a shell configuration file exists at time of MacPorts installation without a DISPLAY variable, the postflight script sets a DISPLAY variable as shown below. The DISPLAY variable is always omitted on Mac OS X 10.5 or higher.
```
export DISPLAY=:0.0
```

Verify the Configuration File

To verify that the file containing the MacPorts variables is in effect, type env in the terminal to verify the current environment settings after the file has been created. Example output for env is shown below.

Changes to shell configuration files do not take effect until a new terminal session is opened.

MANPATH=
TERM_PROGRAM=Apple_Terminal
TERM=xterm-color
SHELL=/bin/bash
TERM_PROGRAM_VERSION=237
USER=joebob
__CF_USER_TEXT_ENCODING=0x1FC:0:0
PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
PWD=/Users/joebob
EDITOR=/usr/bin/pico
SHLVL=1
HOME=/Users/joebob
LOGNAME=joebob
DISPLAY=:0.0
SECURITYSESSIONID=b0cea0
_=/usr/bin/env

Optional Editor Variables

You can set an environment variable in order to use your favorite text editor with the port edit command.

MacPorts will check MP_EDITOR, VISUAL and EDITOR in this order, allowing you to either use a default editor shared with other programs (VISUAL and EDITOR) or a MacPorts-specific one (`MP_EDITOR).

For example, to use the nano editor, add this line to your bash config:

export EDITOR=/usr/bin/nano

To use the user-friendly GUI editor BBEdit (installation required), add this line:

export EDITOR=/Applications/BBEdit.app/Contents/Helpers/bbedit_tool

To keep a command-line text editor as default while using BBEdit with portfiles, add this:

export EDITOR=/usr/bin/vi

export MP_EDITOR=/Applications/BBEdit.app/Contents/Helpers/bbedit_tool