This chapter describes using port, port variants, common tasks and port binaries.
Netstat on os x doesn't do what you hope it does - show port numbers for applications. Here's a snippet for your.bashprofile: # replacement netstat cmd to find ports used by apps on OS X alias. I wanted to see the process using that port in my OSX terminal, and my first thought was to do the following: netstat -a. Stack Exchange Network Stack Exchange network consists of 176 Q&A communities including Stack Overflow, the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.
port is the main utility used to interact with MacPorts. It is used to update
Portfiles and the MacPorts infrastructure, and install and manage ports.
help action shows some brief information about the specified action, or if no action is specified, shows basic usage information for port in general.
selfupdate action should be used regularly to update the local ports tree with the global MacPorts ports repository so you will have the latest versions of software packages available. It also checks for new releases of MacPorts itself, and upgrades it when necessary.
selfupdate detects that a newer version of MacPorts is available, it automatically updates the installed copy of MacPorts base to the latest released version. In that case, you will see this message:
selfupdate procedure fails you'll see a message like this:
As always, you can use the debug flag
-d to enable verbose output. If your
selfupdate failed, re-run it with debug output enabled to see all output generated by the build system.
The output may give you an idea why the build failed. Look for the first occurrences of “error”. If you cannot figure out what's wrong yourself, feel free to ask on the
<[email protected]> mailing list and attach the output generated by sudo port -d selfupdate.
selfupdate accepts a single switch:
Only update MacPorts itself, do not update the tree of
sync action performs a subset of
selfupdate. It synchronizes the ports tree, as does
selfupdate, but it does not check for MacPorts upgrades. On macOS, unless there is a special reason not to do so, run selfupdate instead.
sync does not accept any switches.
diagnose action checks for common issues in the user's environment and reports all issues it finds to the user, along with possible fixes for said problem.
diagnose accepts a single switch:
Only displays warnings and errors, rather than the status of all tests run.
reclaim action attempts to reclaim space by uninstalling inactive ports, and removing unnecessary files that were downloaded during the installation process.
reclaim accepts switches to configure automatic reminders. If passed, the reclaim process will not be run.
Enable regular reminders to run port reclaim.
Disable regular reminders to run port reclaim.
list action lists the currently available version of the specified ports, or if no ports are specified, displays a list of all available ports. The list of available ports is very long, so use search if you are looking for a specific port.
port list always lists the most recent version available in MacPorts, which is not necessarily the version you have installed. For this reason, port list installed likely produces unexpected output. In most cases where you would
echo is the better choice instead. Both port installed and port echo installed would produce the output you might expect from the command, port list installed will not (and, to make matters worse, will be slow).
You will hardly need port list at all to work with MacPorts. When searching, port search is the better choice and when trying to list ports, port installed and port echo are much more useful.
search action allows finding ports by partial matches of the name or description. Other fields can be matched against, and matched in different ways, by using options. port search is the tool of choice if you are looking for a specific software in MacPorts. We recommend you read up on some of its flags to improve your efficiency when searching for ports. Run port help search for an exhaustive list of possible switches.
Suppose you are looking for PHP in MacPorts. You might start with port search php and notice your query produces a lot of output. In fact, at the time of writing this, this search produces 661 matches. By default, port search searches both name and description of a port. While we're looking for PHP, we can reduce the number of hits by using the
--name flag. Furthermore, we only want ports whose name starts with “php”, so we add the
--glob flag (actually, we could leave it out because it is the default) and modify the search term to
Furthermore, we can enable compact output by using the
--line switch. This causes only a single line to be printed for each match:
Among a large number of PHP modules you will find the main PHP ports, which are named php
<version>. Choose one to install.
If you know regex and know about the format of the PHP versions, you can further reduce the output of port search:
Let us look at another example that is less complicated. Assuming you are looking for
rrdtool, a popular system to store and graph time-series data, the simple search approach works well:
The possible switches to
search and their meaning are:
Match the search string in a case-sensitive manner.
Match the literal search string exactly.
Treat the given search string as glob search string (i.e., expand wildcards
[chars]). This is the default behavior.
Treat the given search string as regular expression.
Test the search string against
<field>. Can be specified multiple times to test against multiple fields. The default is
--name --description. Possible values for
Search for ports in a given category.
Search for ports that depend on the port given as search string. The
--depends is an alias for all other
--depends_ options combined. Note that only dependencies specified in default variants will be found.
Test the search string against ports' descriptions.
Test the search string against the homepage field of all ports.
Search for ports maintained by a specific maintainer.
Search only ports' names.
Test the search string against the path of the directory that contains the port.
Search for variant names.
info action is used to get information about a port: name, version, description, variants, homepage, dependencies, license, and maintainers.
deps action lists the dependencies of a port. Dependencies are the packages are required by a port at runtime (library and runtime dependencies) or required to install it (build, fetch, and extract dependencies).
Note that the list of dependencies might depend on the variants you chose. For example, choosing the
+openldap variant of
apache2 adds a dependency on
deps accepts two switches:
Do not read the
Portfile to determine dependencies. Instead, rely on the information cached in the port index. Note that (despite specifying them), this option will ignore any effects of variants. It is, however, much faster.
Exclude dependencies only required at build time, i.e., fetch, extract, and build dependencies.
variants action allows you to check what variations of a port are available before you install it. Variants are a way for port authors to provide options you can use to customize your build at install time. See Invoking Port Variants below to install ports that have variants.
This output lists all variants followed by their description. If a variant depends on or conflicts with other variants, a line detailing that follows. A variant name prefixed by
+ indicates that it has been enabled (on the command line), while a prefix
- indicates that it has been disabled. When bracketed, a prefix
+ means that the variant is enabled by default. Any
 are derived from the
() are derived from the
variants.conf. See Section 6.2.3, “variants.conf” for more information on
install is used to install a port. Once you determined the name of a port you want (possibly using port search), you can install it using this command. See Section 3.2.1, “Invoking Variants” on how to choose variants when installing a new port. For example,
apache2 port without the
preforkmpm, but with the
If the installation of a port fails, you can enable verbose or debug output by giving the
-d flag to port:
All debug information is also kept in
main.log for the port you installed. Its path will be printed automatically if the installation fails. You can manually get the path using port logfile portname. Note that logfiles will automatically be deleted on successful installation.
If the installation of a port fails, you should always clean and try again, i.e., run
and re-execute the command you ran before.
You might also want to try enabling trace mode, which can prevent conflicts caused by files installed by other ports or in common system locations, such as
/usr/local. To do that, re-run the installation with the
-t flag, i.e.,
If the port still fails to install after you have followed these steps, please file a ticket and attach the
main.log of a clean attempt.
The installation of a single port consists of multiple phases. These phases are fetch, extract, patch, configure, build, destroot, archive, and finally install. You may break up a port's installation into smaller steps for troubleshooting by using the name of one of these phases as action rather than
install. For example
will run the installation of
apache2 until the destroot phase. See Section 5.3, “Port Phases” for a complete list of phases and a detailed description.
install takes the following switches:
By default, a binary sanity check called
rev-upgrade is run automatically after each successful installation. Pass this flag, if you want to avoid running this step, for example if you want to run it explicitly later after a number of installations using sudo port rev-upgrade, or if you know it will detect problems but want to defer dealing with them.
By default, each port you install using the
install explicitly (contrary to ports installed as a dependency of a different port) is marked as “requested”. If you want MacPorts to treat a port you installed manually as if it was automatically installed as a dependency (e.g., if a dependency failed to build and you re-tried installing the dependency only), pass this flag.
notes action is used to display any notes that a port's author included. These can contain anything, but by convention are brief, and typically contain quick start steps for configuring and using the port, pitfalls to watch out for, or other information that users should be aware of. These same notes are also displayed after installing a port. Many ports have no notes. More extensive documentation can often be found at a port's homepage, or in its installed files.
clean deletes intermediate files created by MacPorts while installing a port. A port clean is often necessary when builds fail and should be the first thing to try after a failed installation attempt.
port clean can also be used to remove corrupted downloads after a failed
fetch phase, by specifying the
deletes all files that have been downloaded for the given port.
clean accepts the following options:
Remove temporary archives.
Remove downloaded files.
Remove log files.
work directory, i.e., the directory used by MacPorts to build a software. This removes all traces of an attempted build and is the default operation.
All of the above combined.
uninstall action will remove an installed port. It is one of the actions you will use fairly often in MacPorts.
MacPorts will refuse to uninstall ports that are still needed by other ports. For example:
You can recursively uninstall all ports that depend on the given port before uninstalling the port itself to work around this. To do that, use the
You can also override this safety check using the
-f (force) flag. Since this will obviously break the dependents you shouldn't do this unless you know what you are doing.
Uninstalling a port will not uninstall ports that have been automatically installed as dependencies of the uninstalled port and are otherwise unused. You can trigger this behavior by passing the
--follow-dependencies flag. Ports that were manually installed (i.e., are marked as “requested”) or have other dependents will not be removed. You can manually uninstall the unneeded ports later using the
leaves pseudo-port, e.g., using sudo port uninstall leaves.
uninstall supports the following switches:
Recursively uninstall ports that depend on the specified port before uninstalling the port itself. See also the textual description above.
Also uninstall ports that were automatically installed as dependencies of the removed port and are no longer needed.
Avoid running any uninstall hooks, such as commands that update cache files.
contents action displays a list of all files that have been installed by a given port. You can only use
contents for ports you installed.
Common uses for
contents are finding the location of a port's executable after installing it. The following line is usually helpful in this case:
-q (quiet) flag suppresses the header line in this case, but is not strictly necessary.
Prints a human-readable representation of the files' sizes.
Used in conjunction with
--size to choose the unit of the file size. Valid parameters for
List sizes in bytes.
List sizes in
KiB, i.e., 1024 bytes.
List sizes in
MiB, i.e., 1024 * 1024 bytes.
List sizes in
GiB, i.e., 1024 * 1024 * 1024 bytes.
List sizes in
kB, i.e., 1000 bytes.
List sizes in
MB, i.e., 1000 * 1000 bytes.
List sizes in
GB, i.e., 1000 * 1000 * 1000 bytes.
installed action displays the installed versions and variants of the specified ports, or if no ports are specified, all installed ports. It also displays whether a port is “active”, i.e., whether the files belonging to this port are currently present on disk or inactive, i.e., stashed away in a compressed tarball.
-v to also display the platform and CPU architecture(s) for which the ports were built, and any variants which were explicitly negated.
outdated action checks your installed ports against the current ports tree to see they have been updated since you installed them. Note that you will only get new versions by updating your ports tree using
port outdated lists the ports for which an upgrade is available and on the second column, why MacPorts thinks the port needs an upgrade. In most cases, this will be an increase in the version number. If it isn't, more details will be given.
upgrade action upgrades installed ports and their dependencies to the latest version available in MacPorts. In most cases, you will run
to update all ports that have an upgrade available. You can, however, selectively upgrade ports if you want to delay other upgrades until later. This is not recommended unless you know what you are doing, since you might experience software errors for the ports that have not yet been upgraded. To upgrade individual ports, specify the name(s) of the port(s) to upgrade:
Note that MacPorts may decide to upgrade other dependent ports before upgrading the port you requested to be updated. Do not attempt to prevent this, since it will very likely lead to problems later.
upgrade does not uninstall the old version of a port. Instead, it deactivates it, i.e., it stashes the files belonging to the older version away in a tarball. This allows you to go back to the older version if there happens to be a problem with the updated one. To do that, run
to determine the version number of the old version you want to re-activate, and run
to go back to the old version.
If you do not want to keep the old versions around while upgrading, you can pass
-u when upgrading:
However, we instead recommend keeping the older versions around for a while and running
once in a while.
upgrade accepts a number of switches:
Always consider the given ports outdated, regardless of whether they actually are.
If the installed variants do not match those requested, upgrade (and change variants) even if the port is not outdated. You can use this to switch the variant selection on an installed port, e.g., using
--enforce-variants will also enforce your variant selection in all dependencies. If you know this is not necessary, you can avoid processing dependencies using the global
Do not automatically install replacement ports for a port that you have installed, but was replaced with a different one.
dependents action reports what ports depend upon a given (installed) port, if any.
dependents does not work for ports that are not installed on your system. If you want to find out, which ports depend on a port that you have not installed, you can use
This command will, however, not cover dependencies that are only present in non-default variants.
livecheck action checks to see if the application corresponding to a given port has been updated at the developer's download site. This action is mostly useful for port maintainers to determine whether their port needs to be updated, but other may also wish to see if a port packages the latest available version. See Section 5.8, “Livecheck / Distcheck” for more information on livecheck.
livecheck finds no higher version at the port's download site, it prints nothing. The option
-d (debug) may be used for detailed livecheck processing information.
The lint action checks if the
Portfile conforms to the MacPorts standards specified in Portfile Development. You should use this if you modified a
Portfile before submitting patches back to MacPorts.
Portfile validates fine the following message is shown.
Otherwise the warnings and errors are listed.
lint has the following flag:
Enables additional checks that are mostly whitespace-related and best practices.