== Migrating a MacPorts install to a new major OS version or CPU architecture ==

An installation of MacPorts and the ports installed by it are only designed to work on a single OS release and a single CPU architecture. If you upgrade to a new OS version (e.g. from Tiger to Leopard) or migrate to a new machine with a different type of CPU (e.g. PowerPC to Intel), you may get lucky and have your ports keep working, but in general, things will break.

After performing either of these types of system upgrades, you will first need to install the base MacPorts system again, either from the appropriate disk image or from source. (You will probably not be able to use `sudo port selfupdate` because the old `port` command you have will probably not be compatible with your new system.) You must then reinstall all your ports. There are at least two ways you could do this.

First of all, install the latest Xcode for your new Mac OS X version. Note that this will not automatically be installed on upgrades, you will have to do it manually. You will find the Xcode installer on the DVD.

=== Manual method === #manual

The most reliable way to reinstall your ports is as follows:

 1. Save the list of installed ports:
{{{
port installed > myports.txt
}}}
 2. Clean any partially completed builds, and uninstall all installed ports:
{{{
sudo port clean installed
sudo port -f uninstall installed
}}}
 3. Browse `myports.txt` and install the ports that you actually want to use (as opposed to those that are only needed as dependencies) one by one, remembering to specify the appropriate variants:
{{{
sudo port install portname +variant1 +variant2 ...
}}}
Note that if you have specified variants which are not the default, you may need to install ports in an order other than the alphabetical order recorded in `myports.txt`.

=== Automatic method === #automatic

As of MacPorts 1.8.0, you can alternatively try an automated rebuild of all installed ports for your new platform using these steps:

 1. Uninstall the gawk, grep, and gsed ports (if installed), as many build systems will try to use them even if there is no dependency:
{{{
sudo port -f uninstall installed and \( gawk grep gsed perl5 perl5.8 perl5.10 \)
}}}
 2. Reinstall all installed ports:
{{{
sudo port upgrade --force installed
}}}
 3. If MacPorts has not already reinstalled them, you can now reinstall any of the ports removed in step 1, if desired.

Note that this method may sometimes fail if the dependency relationships declared by the ports are not completely accurate, or if ports other than gawk/grep/gsed are used opportunistically. If you encounter such a problem, please report it so we can fix it.