Migration Assistant: what it moves, what it quietly leaves
· 6 min read
Migration Assistant does most of the work of moving to a new Mac, which is why the gaps catch people out. The things it misses are not random; they are consistent, and knowing them in advance turns a fortnight of small surprises into a checklist.
What comes across reliably
Your home folder. Documents, Downloads, Desktop, Pictures, Music, and the hidden Library folder inside it, which is where most applications keep your settings. This is the bulk of it and it is dependable.
Applications. Anything in the Applications folder. They arrive as they were, including their versions, which is worth noting: migration does not update anything.
User accounts. Including passwords, so you log in on the new machine exactly as you did on the old one.
Keychain. Saved passwords, certificates and Wi-Fi networks.
System settings. Most of what you set in System Settings, plus printers, network locations and shared folder configuration.
What does not come across
Software licences that check the hardware. Applications licensed to a specific machine frequently see a new one and ask you to activate again. Usually fine, occasionally a problem if the licence allows a limited number of machines and the old one still counts. Deauthorise on the old Mac before erasing it.
Anything outside the standard locations. Files stored at the root of the drive, in /Users/Shared, or in a folder you created outside your home directory may not be selected. Check for them explicitly.
Command-line tools and package managers. Software installed through a package manager typically lives in /usr/local or /opt, outside your home folder. Some of it migrates, some does not, and what does often needs reinstalling anyway because it was compiled for a different architecture.
Virtual machines and container images. Large, frequently stored outside the home folder, and often better recreated than moved.
Other users’ accounts, unless you select them. Easy to miss on a shared family Mac.
FileVault recovery keys. These are per machine. The new Mac generates its own when you enable FileVault, and the old key is meaningless on it.
The check worth doing before you start
Fifteen minutes that prevents most of the trouble.
Look at what is actually on the old Mac outside your home folder:
ls -la /Users/Shared
ls /usr/local 2>/dev/null
ls /opt 2>/dev/null
Anything there that matters should be copied by hand, because migration may not offer it.
Then list your applications and note which ones you paid for outside the App Store:
ls /Applications
For each, find the licence now rather than later. Purchase emails are the usual source, and searching your mail for the application name generally finds them. Transferring apps when you have lost the licences covers the harder cases.
Choosing what to bring
Migration Assistant presents four categories with checkboxes: Applications, Users, Settings, and Other files and folders. You do not have to take all of them.
The most useful combination for a machine you want to stay clean is Users only. You get your files and your per-application settings from ~/Library, without the system configuration and without applications that may be years out of date.
The most useful combination for continuity is everything, which is the default and is the right choice if the old machine was behaving well. Should you migrate or start clean covers that decision.
During the transfer
Use a cable if you can. Thunderbolt or Ethernet is dramatically faster than Wi-Fi, and more importantly it is more reliable over a long transfer.
Keep both machines plugged in. A migration interrupted by a flat battery is not dangerous, and it does mean starting again.
Turn off sleep on both machines for the duration. On the old Mac, running this in Terminal keeps it awake until you press Control-C:
caffeinate -d -i
Expect it to take a while, and expect the time estimate to be wrong in both directions. It settles down after the first few minutes.
Afterwards
Three things to check on the new Mac.
Login items. System Settings, General, Login Items. Migration brings background helpers across, including ones belonging to applications you removed long ago. Login items on a Mac covers auditing them.
Privacy permissions. System Settings, Privacy & Security. Some permissions do not migrate and applications will ask again on first run.
iCloud. Sign in and let it settle before judging what is missing. Files stored in iCloud may show as placeholders until downloaded, which looks like data loss and is not. Files that show a cloud icon covers that.
Then keep the old Mac for a fortnight before erasing it.
Questions
Can I migrate from a Time Machine backup instead of the Mac itself? Yes, and it is a good option if the old machine is not working. Migration Assistant accepts a Time Machine drive as a source.
Can I migrate from a Windows PC? Yes, with the Windows Migration Assistant installed on the PC. It moves documents, contacts, calendars and mail, not applications. Moving from Windows to a Mac covers the wider move.
What if I already set up the new Mac? Migration Assistant still runs, from the Utilities folder. It will usually create a second user account rather than merging into your existing one, which you can then move files out of.
How do I know it finished properly? Compare a few folders by size on both machines, and open two or three applications you rely on. A transfer that ended early usually shows as a home folder noticeably smaller than the original.