New Ticket     Tickets     Wiki     Browse Source     Timeline     Roadmap     Ticket Reports     Search
Last modified 3 months ago Last modified on 05/19/14 15:23:18

Table of Contents

  1. 1. Install Xcode Tools
  2. 2. Install XWindows (X11) (optional)
  3. 3. Set the shell environment
    1. Requirements for the MacPorts' shell environment
    2. Verify the shell environment
    3. Options for the MacPorts' shell and X11 environment
  4. 4. Install MacPorts
    1. Install MacPorts using the binary installer (to /opt/local/ only)
    2. Install MacPorts from source (to any path except /usr/local/)
    3. Install MacPorts from source as an unprivileged (non-root) user
    4. Install MacPorts from a developer release
  5. 5. Update MacPorts via selfupdate

1. Install Xcode Tools

  1. Download and install the latest version of Xcode Tools for your Mac OS X version. It is best not to install an older version from the Mac OS X install disk, since it may have bugs that cause some ports to fail to install. Latest versions are 2.5 for Mac OS X 10.4, 3.1.4 for Mac OS X 10.5, 3.2.6 or 4.2 for Mac OS X 10.6, 4.6.3 for OS X 10.7, and 5.0.2 for OS X 10.8 and 10.9.
    • In Xcode 5.x the command line tools are installed by running xcode-select --install in the Terminal.
    • In Xcode 4.x the command line tools are installed by selecting Xcode Preferences/Downloads and clicking the "Install" button adjacent to :Command Line Tools
  2. Run the binary installer, or in the case of Xcode 4.3 drag the program to /Applications and then follow the migration instructions.
  3. Click Customize, expand the Applications category and click the checkbox beside X11 SDK to add it to the default items.
  4. Click Install to install Xcode Tools and the X11 SDK.

Notes: Xcode Tools is not updated via the Software Update utility on OS versions prior to 10.6.

2. Install XWindows (X11) (optional)

On Mac OS X 10.4, Apple's X11 is an optional install. If the application X11 is not present in /Applications/Utilities, then the traditional way to put it there would be to do the following:

  1. Insert the "Mac OS X Install Disk 1" and run the package named "Optional Installs".
  2. At the software selection window expand the Applications categoty and click the checkbox beside X11 (and nothing else).
  3. Click Install to install X11.
  4. Drag the /Applications/Utilities/X11 icon to your dock — you must open X11 manually before launching an X11 application. (This is not necessary on Leopard and later, as X11 will be launched automatically when needed.)


  • Some form of XWindows (X11) is required for many MacPorts apps, and it is recommended that you install it (in one way or another) even if you are not planning to run X11 apps immediately. Note that this recommendation is not a requirement though.
  • The files provided by the X11SDK are also required to run some X11 software, but the X11SDK is (or at least used to be) installed by default during the Xcode Tools install above. If you wish to check to see if the X11 (X11User) and X11SDK packages are installed, then you should look in /Library/Receipts for the files X11User.pkg and X11SDK.pkg.
  • On newer versions of OS X, Apple's X11 has been replaced by a shim application that prompts the user to install XQuartz, which is basically the same thing as Apple's X11, except hosted on MacOSforge instead of on Apple's website proper. Installing XQuartz will also work for the purposes of the recommendation above to install X11 for use with MacPorts.
  • It is also possible to build X11 from source with MacPorts, as the packages that make up X11/XQuartz all have Portfiles for them in MacPorts as well (the same person maintains both XQuartz and all of the X11 ports in MacPorts). There is an entry in the FAQ explaining how some of these ports might end up getting installed anyways. The xorg port exists as an umbrella port to allow installing all of these ports in a single command (i.e. "sudo port install xorg").

3. Set the shell environment

Setting the Unix shell environment is critical for MacPorts to function.

Requirements for the MacPorts' shell environment

The MacPorts binary installer places a .profile file in your home directory (view files preceded by a dot with 'ls -a'). The contents of this ~/.profile file adds the MacPorts paths in front of the standard Unix paths for the default BASH shell. This is done so that if you have utilities or libraries from both MacPorts and Mac OS X's standard install, the MacPorts libraries will be run instead of the ones provided by Apple.

export PATH=/opt/local/bin:/opt/local/sbin:$PATH

On Mac OS X versions 10.4 and earlier, you'll need to add this variable to your ~/.profile to run X11 applications:

export DISPLAY=:0.0

Do not set DISPLAY on Mac OS X 10.5 (Leopard) or later, as it is set automatically and needs to be a different value.

So a basic ~/.profile file will look something like this:

export PATH=/opt/local/bin:/opt/local/sbin:$PATH
export DISPLAY=:0.0

Important Notes:

  • To understand why MacPorts libraries are often installed when Apple has provided one, see FAQ.
  • Changes to ~/.profile do not take effect on the current shell session — they take effect on new sessions so open a new shell session and type 'env' to see the path and variable changes.
  • Other profile files may take precedence over ~/.profile. If you are using one of the following profile files in your home directory, you will need to merge the contents of it into ~./profile, or vice versa because the shell will ignore one of them:
    • ~/.bash_login
    • ~/.bash_profile

Verify the shell environment

To verify that your ~/.profile has set your shell environment:

  1. Open a new terminal window
  2. Type the command: env

Check to make sure the reported path begins with the MacPorts' paths as show above.

Sample output of command env:


Options for the MacPorts' shell and X11 environment

To set a default editor for use with the port command (e. g. 'port ed mysql5'), add a variable EDITOR with the path of your favorite editor to the ~/.profile file.

export EDITOR=/usr/bin/pico

A sample ~/.profile with optional EDITOR variable set:

export PATH=/opt/local/bin:/opt/local/sbin:$PATH
export DISPLAY=:0.0
export EDITOR=/usr/bin/pico

To launch X11 apps directly from an X11 window (instead of a terminal window), you need to have the MacPorts paths imported into X11 sessions when they are opened. This is a two step process.

First, tell X11 about your .profile file by editing the file /etc/X11/xinit/xinitrc and add this line near the top.

source ~/.profile

Now finish by making any subsequent X11 sessions opened using the menubar respect your .profile.

  1. Open X11 and select "Customize Menu ..." from the Applications menu.
  2. Double-click the menu item "Terminal" and change: xterm to xterm -ls
  3. Click "Done" to save the change.

4. Install MacPorts

Install MacPorts using the binary installer (to /opt/local/ only)

  1. Download the latest MacPorts .dmg disk image.
  2. Run the binary installer.
  3. Perform the default “easy” install.


  • A MacPorts' selfupdate (see below) will automatically update to the latest release if the binary .dmg image is behind the latest released tarball.

Install MacPorts from source (to any path except /usr/local/)

  1. Download and unzip the latest MacPorts tarball from the MacPorts download area.
  2. Perform these commands in a terminal window.
    cd ~/MacPorts-2.2.0/
    ./configure --enable-readline
    sudo make install

You should not enable readline support if you have a custom readline installation in /usr/local, as it can cause problems with the build.


  • To see why /usr/local is not a viable install location for MacPorts, see FAQ
  • If you install MacPorts to a non-default location (i.e. anywhere other than /opt/local), then you cannot use the default binary archives, so therefore you will have to build all packages from source. See the BinaryArchives wiki page for more information.

Install MacPorts from source as an unprivileged (non-root) user

If you don't have root access on your machine, or if you just prefer to install packages without becoming root, the following steps will install MacPorts into ~/macports (tested on Leopard and Tiger).

tar -jxf MacPorts-2.2.0.tar.bz2 && cd MacPorts-2.2.0
PATH=/usr/bin:/usr/sbin:/bin:/sbin ./configure \
    --enable-readline \
    --prefix=$HOME/macports \
    --with-install-user=`id -un` \
    --with-install-group=`id -gn` \
    --with-tclpackage=$HOME/macports/share/macports/Tcl \

As noted above, you should omit --enable-readline if you have a custom readline installation in /usr/local.

For more information about other useful flags, run ./configure --help. After you have successfully configured MacPorts for your local install, you can install it simply with the commands:

  make install
  • After you have successfully installed MacPorts to your local directory, add something like the following to your Mac's ".bashrc":
  export PATH=$HOME/macports/bin:$HOME/macports/sbin:$PATH
  export MANPATH=$HOME/macports/share/man:$MANPATH
  export PERL5LIB=$HOME/macports/lib/perl5/5.12.4:$HOME/macports/lib/perl5/vendor_perl/5.12.4:$PERL5LIB

Note: do not set MANPATH here unless you have already set it elsewhere (or are running Leopard, which does so). If you have not set MANPATH in another place, and are running Tiger or earlier, omit the MANPATH line. For more information about setting up the shell environment variables correctly, please see the Guide.

Most ports install just fine unless they try to add themselves to the LaunchD (e.g. most services, but you'd need root for most of them anyhow). If you do run into a required port that tries to add itself as a startup item, you can edit the Portfile (e.g. port edit <portname>) and change startupitem.create yes to startupitem.create no

Install MacPorts from a developer release

Under construction...

Note: Developer releases are primarily for developers who are working on base, and as such, they may contain untested code and may have bugs. Use at your own risk.

5. Update MacPorts via selfupdate

The 'port selfupdate' command must be run after a new MacPorts install, and frequently thereafter. The command updates MacPorts with the latest port revisions, and, if necessary, updates MacPorts to the latest release.

  1. Open a terminal window.
  2. Execute the MacPorts selfupdate command.
sudo port selfupdate

or for verbose output:

sudo port -d selfupdate