There is also a [wiki:howto HOWTO section], which may answer some questions not listed here and provides useful tutorials for performing a number of different tasks using MacPorts.

[[PageOutline(2-3,Table of Contents,inline)]]

== General Questions ==

=== A port fails to build. What should I do? === #buildfails

Before filing a ticket in the issue tracker, please make sure you have the latest version of MacPorts and of the ports tree by running

{{{
sudo port selfupdate
}}}

Also, make sure you have the latest version of Xcode. Old versions of Xcode are known to make certain ports fail. Then run
{{{
sudo port clean <portname>
}}}
to clean the work directory for the port that failed to build, followed by
{{{
sudo port upgrade outdated
}}}
to upgrade your installed ports to the latest available versions. Then you can try your original command again.

If this does not help, check ProblemHotlist (and SnowLeopardProblems if you are on Mac OS X 10.6) and see if your issue is mentioned. If not, [search:] for an existing ticket. If there does not appear to be one, you can then [http://guide.macports.org/#project.tickets create a new ticket].

=== I get the error "C compiler cannot create executables" or "can't read "build.cmd": Failed to locate 'make' in path" when I try to install a port. Why? === #missingxcode

You need to install [http://www.macports.org/install.php#requirements Xcode].
Ensure you include both System Tools and Unix Development.

=== How do I upgrade my Xcode install? === #upgradexcode

Some ports need newer versions of Xcode than that which ships with the OS, and will fail to install with older versions due to that requirement.  Apple has begun updating Xcode via Software Update on Mac OS X 10.6, but on older OS releases you have to download new Xcode versions manually.  To do so, go to http://connect.apple.com/ and log in with your Apple ID (the free online developer account is enough to get access to Xcode).  Once you log in, go to ''Downloads'', then select ''Developer Tools'' on the right section under ''Downloads''.  You can then search for Xcode (there are quite a few versions available, make sure to get the latest for your OS version) using your browser, via Cmd-F.

=== Will my MacPorts install continue to work after installing a new major OS release or migrating to a new machine with a different CPU architecture? === #migration
In general the answer is no. See [wiki:Migration] for how to get things working again.

=== Is MacPorts Universal? === #universal

MacPorts works on both Intel- and PowerPC-based Macs, but, by default, the ports you install will be compiled only for the architecture you're currently running on. This means that if you migrate from, say, a PowerPC Mac to an Intel one and use Migration Assistant to copy your data to the new machine, you should reinstall all your ports on the new machine to rebuild them for Intel. See the Migration link in the previous question.

For many ports, there's now an alternative: select the +universal variant when you build each port, and MacPorts will create universal binaries that work on multiple processor architectures. The set of architectures is controlled by the `universal_archs` setting in [http://guide.macports.org/chunked/internals.configuration-files.html#internals.configuration-files.macports-conf macports.conf].

Using +universal can allow you to run ports which do not build for your preferred architecture alongside those that do. For example, the wine port only builds for i386, but shares many dependencies with ports that can build for x86_64. On x86_64 hardware, the dependencies can be built with +universal so they support both i386 and x86_64 dependents.

Historically, +universal could also be useful if you anticipated migrating to a different Mac soon, or if you wanted to install MacPorts on an external hard drive used by both Intel- and PowerPC-based Macs. But note that because +universal is not necessarily tested by port maintainers, it may not work correctly for all ports, even if no error message is shown during installation. If you find a port that will not build with +universal, or if it builds but then does not work correctly, please file a bug report. If you can provide a patch to fix the problem, that's even better.

Some ports may only work on PowerPC Macs or only on Intel Macs. Others may work on 32-bit archs but not 64-bit. In some cases, these are bugs that need to be fixed. If there is a newer version of the software available, you should report this to the port maintainer. Maybe the new version works correctly on both architectures. If the port is already using the latest version, report the problem to the upstream authors of the software; the software may need to be updated. In other cases, the software may be specifically written for one processor architecture such that it will not be possible to make it available to the other.

See also [wiki:Universal] for a (highly outdated at this point) list of ports that were tested for +universal support and the results.

=== Why is /opt/local the default install location for MacPorts? === #defaultprefix

`/opt/local` was chosen so as to avoid stomping on other various installations (e.g. fink uses `/sw` to do the same); `/usr/local` is not a viable choice for several reasons:
 1. Some software (especially auto* tools from Gnu) look in `/usr/local` as a default location, which means MacPorts can't be easily isolated when needed
 2. `/usr/local` is usually reserved for the given system's admin to install items local to that system, and tends to be a bad choice to have taken over by a non-system port system
 3. gcc considers `/usr/local` to be a standard system directory, causing (at least) the include directory to be unable to appear early in the list of include directories, and hence causing MacPorts-installed items to be difficult to use properly for items which need them (where another version is installed elsewhere, like `/usr/X11R6`)

=== How do I remove or uninstall MacPorts? === #uninstall

See [http://guide.macports.org/chunked/installing.macports.uninstalling.html the Guide].

=== What are the folders in `${prefix}/var/macports/` for and why do they take up so much space? === #diskspace

`man porthier` says: "MacPorts runtime data", but it contains some more subfolders:

`build`
 Is used during the building of ports, usually it contains only empty folders, does not take much space. During the building of a port there is a soft link `${prefix}/var/macports/sources/rsync.macports.org/release/ports/<category>/<name>/work` pointing to the corresponding folder here.

`distfiles`
 The downloaded sources of each built port, could be removed with `port clean --dist <port>`.

`packages`
 Contains the binary archives of each installed port. Could be removed with `port clean --archive <port> <version>+<variant>`. These files are helpful for uninstalling and later reinstalling the exact same ports (eg. for testing something). Only unpacking the archive is needed and no build will be performed. If these archives are never needed they can be disabled in `${prefix}/etc/macports/macports.conf` with the `portarchivemode` option.

`registry` and the older `receipts`
 Contains detailed information about each installed port, e.g. which files belong to the port with corresponding checksums.

`software`
 Contains the installed software itself. If a port is activated its files are hard links in the `${prefix}` folders to the corresponding files here. `port uninstall <port> <version>+<variant>` would remove it from here, but then this port can not be used anymore.

`sources`
 In the subfolder `rsync.macports.org/release/base` are the MacPorts sources themselves (e.g., for the port(1) command). A `port selfupdate` updates this from the MacPorts rsync server.
 In the subfolder `rsync.macports.org/release/ports` are folders for each port category and the ports themselves therein, where the corresponding Portfile and patches are found. `port sync` and also `port selfupdate` update this from the MacPorts rsync server.

=== I get `Error: checksum (md5/sha1/rmd160) mismatch for port`. What can I do about it? === #checksums

MacPorts computes checksums of downloaded files to ensure they aren't corrupted and haven't been tampered with. Each portfile lists the checksums for the files that the port will download (using md5, sha1 and/or rmd160). If the computed checksum of the downloaded file doesn't match the one listed in the portfile, that means the file you downloaded is not the one the port designer used when creating the port, and so MacPorts stops the installation.

First aid, download the file again:
{{{
$ sudo port selfupdate
$ sudo port clean --dist <portname>
$ sudo port install <portname>
}}}

If this doesn't help, then you should attempt to discover why there is a checksum mismatch.

'''Please do NOT file a ticket without first ruling out a misconfiguration on your end. Also make sure that you specify which mirror your download came from when filing a ticket.'''

There are several possible reasons for checksum mismatches:

 1. ''The file is corrupt''. If it was corrupted by the transfer, download it again (as shown above). If it is corrupted on the server, there is not much you can do about it. Open a bug in [http://trac.macports.org/newticket Trac] and assign it to the port's maintainer. As for solving the problem: if there are other mirrors, try one of them. You can also ask if someone has a complete file they can send you on the [http://lists.macosforge.org/mailman/listinfo/macports-users MacPorts users' mailing list].
 2. ''The developer has performed a "stealth upgrade"''. Sometimes upstream developers make "stealth upgrades" in which they change the contents of their distribution archive but not its version number, without informing MacPorts of this change. Perhaps the developer has repackaged the distribution with a different archiving program, or has fixed typos in the included documentation or made other presumably minor changes that did not warrant a regular release. This practice is not recommended because of the obvious difficulties it presents to MacPorts and other port systems that compute package checksums. Attempt to get confirmation from the developer of the software that this has occurred. If the developer cannot be reached, attempt to determine yourself whether a stealth upgrade has happened. [http://www.google.com/ Search the Internet] and try to locate the older version of the archive that matches the checksum in the portfile. Also download the version currently available on the developer's site, extract both, and compare the contents (for example with `diff -r -u <old> <new>`). If the changes look minor and benign, or there are no changes at all, then it is safe for you to update the checksum in the portfile, and the port maintainer should be informed of this so that they can make the change official. If you cannot determine whether a stealth upgrade has taken place, ask for help on the [http://lists.macosforge.org/mailman/listinfo/macports-users users' mailing list].
 3. ''The file has been tampered with''. It is perhaps somewhat unlikely yet theoretically possible (and it has happened a few times in practice) that the archive being distributed by the developer (or by a mirror) has been genuinely compromised. If a hacker was able to manipulate the developer's (or the mirror's) server, the hacker could have uploaded a revised archive containing malware (a virus, a trojan horse, a spam-sending platform, etc.) of the hacker's choosing, and you would certainly not want to install such software. You must attempt to determine, as above, whether this has occurred by contacting the developer, or by locating an older version of the archive and comparing them. You can also contact the port maintainer or the [http://lists.macosforge.org/mailman/listinfo/macports-users users' mailing list].
 4. ''A proxy is blocking your request''.  Some internet connections are protected by a proxy which may not allow file downloads, tar/zip downloads, or may not allow your particular computer to access the internet without being specifically allowed.  In that case, the proxy may return a simple "disallowed" message (with an erroneous 200 status), which MacPorts mistakes for the file that should be downloaded.  Examining the content of the downloaded file will determine if this is the case.  If so, contact your network administrator for access.
 5. ''A download server and/or your DNS server is misbehaving''. See MisbehavingServers.

=== Where can I find a GUI frontend for MacPorts? === #gui

There are several GUIs for MacPorts in development.

 * [http://www.codebykevin.com/portauthority.html PortAuthority] has been around for a long time. It's shareware and costs $20.
 * [wiki:MacPortsGUI Pallet] is a new GUI under development, which can be downloaded from that wiki page.
 * [http://porticus.alittledrop.com/ Porticus] is another new GUI currently in development.

=== What do I do if `port selfupdate` doesn't work or the rsync server refuses connections? === #selfupdatefails

First try `sudo port -d selfupdate` to get all errors to display. If your connection to the rsync server fails you may get blocked by a firewall or other network control software.

Some firewalls, such as PeerGuardian, block connections to certain corporate IP addresses as a way to prevent software from "phoning home" and violating your privacy. Our main rsync server is hosted by Apple Inc. Self updating requires an rsync connection to download files, but this will be blocked. In order to work around this, you need to temporarily disable or white-list rsync.macports.org.  Another alternative is to use [wiki:Mirrors another mirror] that is not hosted by Apple.

The black list entry is all of Apple Inc's subnet, which is 17.0.0.0/8. Disable this or create a white-list exception for rsync.macports.org.  PeerGuardian will filter your network connections even if it is not actively running as an application.   It is possible to disable PeerGuardian before running a selfupdate command by typing the following command in Terminal, but make sure you stop all processes associated with PeerGuardian before doing this.
{{{
sudo kextunload -b xxx.qnation.PeerGuardian
}}}

If you run LittleSnitch, create a rule for rsync (/usr/bin/rsync) that allows connections to server hostname rsync.macports.org, port 873 (rsync), protocol 6 (TCP). Make sure the rule is enabled.

If getting through a firewall is not a possibility, there are other methods you can use which are a bit more manual:

 * [wiki:howto/SyncingWithSVN  You can sync your port tree using Subversion]
 * [wiki:howto/PortTreeTarball You can download a tarball, built daily, and update with that]

=== `port list` produces unexpected output === #portlist

You probably want `port installed` or `port outdated` instead. If you were trying to use `port list installed`, you probably want `port installed` (or, equivalently, `port installed installed`). If you were trying to use `port list outdated`, you probably want `port outdated` (or, equivalently, `port outdated installed`). If you were trying to use `port list someport`, you probably want either `port installed someport` or `port outdated someport`.

For every port specified on the command line (or expanded from pseudo-ports like `installed`), `port list` displays the version of that port currently available in the ports tree -- ''not'' the version currently installed. So if for example you have port '''foo''' installed at versions 1 and 2 (with 2 being the current version available), `port list installed` will show '''foo''' at version 2, twice, whereas `port installed foo` will show '''foo''' at version 1 once and '''foo''' at version 2 once.

=== Why has feature XYZ not been implemented yet, it is important? === #whynotxyz

There are a number of enhancements which would improve MacPorts, but time is finite and the project is perpetually in need of more base-level developers.  This means that new features must be prioritized (bugs usually being more important) and other, useful features don't get implemented for some time.  See [http://guide.macports.org/#project.contributing the guide entry on contributing] for how to get involved if you'd like to help improve MacPorts.

== Software Questions ==

=== Why do I have to install xorg-* ports? === #x11-libs

MacPorts does not use the X11 '''client''' libraries provided by the system and installs its own copy.  This allows for more consistent support for older machines which are not as up to date (especially Tiger which doesn't have a pkg-config compatible X11 SDK).  Most X11 packages in MacPorts are newer than those shipped by Apple and usually reflect the latest work from the [http://xquartz.macosforge.org XQuartz Project].

Don't be scared away, MacPorts built applications are still compatible with the X11 server provided by the system, and any other X11 applications built against the /usr/X11 libraries will work with the MacPorts X11 servers (xorg-server and xorg-server-devel).

=== What does 'Xlib:  extension "RANDR" missing on display "/tmp/launch-XXXXXX/:0"' mean? === #randr

Many X11 programs try to use the RANDR extension, and print this warning when it is not available. The RANDR extension is not available in the Apple-provided X11 server in Snow Leopard and earlier.  It is supported in [http://xquartz.macosforge.org XQuartz] 2.6.0 as well as the MacPorts X11 servers.

Unless you have a specific need for RandR functionality, this warning can be safely ignored.

=== Python fails to build === #pythonfails

If you get an error building Python like 
{{{
Python/mactoolboxglue.c:440: warning: return makes integer from pointer without a cast Python/mactoolboxglue.c:440
}}}
your Xcode installation is incomplete (you are missing e.g. the QuickTime SDK).

=== Will MacPorts link to system libraries rather than its own? === #syslibs

No, MacPorts maintains its own versions of libraries. See the next question for the reason why.

You may find some ports that link with some system libraries. Some of these are intentional, such as in cases where the MacPorts version is missing some crucial functionality (e.g. ports that need Kerberos support use the Mac OS X-supplied library, not the MacPorts one). In other cases these are bugs in the relevant ports, and tickets should be filed so it can be corrected.

=== Why is MacPorts using its own libraries? === #ownlibs

There are several reasons why MacPorts uses its own libraries. It makes ports more consistent across different versions of Mac OS X. For example, if we can rely on openssl 1.0.0 from MacPorts, we don't have to test every port that needs ssl for every available openssl installation. Apple's software tends to break from time to time (e.g. openssl refuses to build with an old zlib, but for awhile Apple shipped the old headers of the vulnerable zlib version). Even if Apple's versions aren't broken, they're rarely up-to-date. Apple has a habit of not updating the libraries in Mac OS X until absolutely necessitated by a security vulnerability.

The drawbacks of this policy are minimal: Wasting a few megabytes for e.g. a Python installation is next to nothing if you have a multi-gigabyte hard disk, and the time required to build the additional ports decreases as computers get faster.

=== GNOME has an empty menu === #gnomemenu

See the [wiki:GNOME GNOME] section of this Wiki for more information.

=== Why do the python ports have so many dependencies? === #pydeps

Earlier versions of the python ports either used variants (python23) or split some modules out from the base port (python24) in order to reduce the number of dependencies for the port.  Using variants is bad as that requires a complete rebuild of the port in order to add a given module (like readline support); also, dependencies can't specify variants currently (see ticket #126).

Using separate ports for these modules (like py-readline) avoids the need to completely rebuild the base port, and can be used as a dependency, but ends up having other issues.  One is that these modules are installed using the standard distutils method for python, which causes them to be installed in a different location than where they would be when installed normally (see ticket #12369).  The other is that many python developers have expectations when they install python, and installing python24 simply does not match that.

=== When should I use the force option (-f) === #whentoforce

Use of the force option (-f) is rarely necessary, but some suggestions in the past have recommended its use quite frequently.  The most common need for -f now is  when you run into a stray file in your MacPorts prefix, not owned by a port, but blocks the install of one.  This is seen with an error message from port similar to
{{{
Error: Activating some-port @1.0_0 failed: Image error: /opt/local/path/to/stray/file already exists and does not belong to a registered port.  Unable to activate port some-port.
}}}
Unless you know the source of that file and that you need to keep it, this is a good use of force.  However, don't use it with '''install''' but with activate:
{{{
sudo port -f activate some-port
}}}

Prior to MacPorts 1.8, -f was also used to force an upgrade of a port to add new variants.  This has now been replaced with the {{{--enforce-variants}}} option to upgrade:
{{{
sudo port upgrade --enforce-variants curl +ssl
}}}
This will install the curl port again, adding the +ssl variant.

=== Using build_arch === #usingbuildarch

MacPorts 1.8 introduced a new option to macports.conf: '''build_arch'''.  This allows you to control the architecture targeted by builds.  For example, you can use this to build 64bit on 10.5 (where 32bit is the default) or 32bit on 10.6 (where 64bit is usually the default).

Documentation on this feature can be found in the man page for ''macports.conf'', and also in the Guide.

There are two issues to note before you try and use build_arch:
 - many ports ignore the {{{-arch}}} flag to select the architecture, and will most likely fail to build at all (if you encounter such a problem, please file a ticket so it can be fixed)
 - you must set build_arch prior to building any ports (must be done on a new, clean install), otherwise you will have major issues due to some ports being of one architecture, and some the other (if you want to switch architectures and have already installed ports, you can uninstall all ports with "`sudo port -f uninstall installed`" and then reinstall ports, or consult the [wiki:Migration Migration] document for an automated script)

=== How can I get a list of all dependencies for a port? === #alldependencies

As of MacPorts 1.9.0, you can just run:
{{{
port rdeps <portname>
}}}

There is also a [http://svn.macports.org/repository/macports/contrib/port-depgraph/port-depgraph script] in the contrib section of the repository that will generate a diagram of the dependencies of a port using graphviz.

== Portfile Development and Maintenance Questions ==

=== Is it possible to have a dependency on a specific variant of another port? E.g. "postgresql8 +server"? === #dependonvariant

No.  This is ticket #126.  The dependency engine is currently unable to handle specifying anything beyond "port X requires port Y" or "port X requires file Z which can be provided by port Y."  There have been discussions on revamping the engine (see the mailing list archives) but nothing concrete as yet.  This is why the most useful variants really shouldn't be variants at all but rolled into the port itself.  It can also sometimes be useful to break variants out into subports or separate ports (e.g. the postgresql83-doc and postgresql83-server ports, instead of having +doc or +server variants of the postgresql83 port).

=== Why won't `portindex` work? I have a local repository set up === #portindexfails

Your local repository needs the ports to be nested within a category for portindex to work, as explained in the relevant [http://guide.macports.org/#development.local-repositories documentation].

=== Why was the `cd` command removed? === #cd

The `cd` command was removed from trunk in r28796. As of release 1.7.0 it is no longer available for use in Portfiles. `cd` is harmful as it changes the current directory of the whole process and not only of the current Tcl interpreter. Also, it becomes unreliable when used inside phases and other phases begin to rely on it.

Please use absolute paths instead, starting with ${worksrcpath}. If you need to run a command with `system`, use it like `system "cd ${worksrcpath} && autoreconf"`.

=== What is the process for becoming a committer? === #committer

The process is pretty much the same as for any other open source project. See the relevant [http://guide.macports.org/#project.membership documentation] and the [wiki:NewCommittersGuide New commiters guide] for what commit access to MacPorts entails.

=== Why Tcl? === #whytcl

These mailing list posts by Landon Fuller, one of the original authors, explain why Tcl was chosen for MacPorts:

[http://permalink.gmane.org/gmane.os.opendarwin.darwinports/369][[BR]]
[http://permalink.gmane.org/gmane.os.opendarwin.darwinports/8826]

== Runtime Errors ==

=== I try to disable a variant, but it just informs me of the proper usage for the `port` command === #disablevariants

When using

{{{ 
port <command> <portname> -<variant>
}}}

the dash in the command is going to be interpreted as an option, hence getting the usage message.  It needs to be escaped away with a double-dash:

{{{
port <command> <portname> -- -<variant>
}}}