Edit: Please note there is a newer version of this guide here: https://astonj.com/clean-macos-install-the-easy-way/
Migration Assistant recently failed to work when I was trying to migrate data from an existing Catalina based Time Machine backup to a new Catalina install (both 10.5.1). I tried 4 times and each time I experienced the dreaded missing emails bug! Since Apple devs are currently on holiday for Thanksgiving (won’t be back until next month) I thought what better time to get back into doing clean installs – where you transfer just what you need to and reinstall everything else, leaving you with a squeaky clean brand spanking new system 🤩
What does this guide cover?
- Backing up your personal files (basically everything in your Home directory)
- A fresh clean install after wiping your disk
- Restoring your files, emails and passwords
Before you start
Before you start you will need to make sure your existing computer is running to the same OS version as your target machine (this just makes things easier). I was going from Catalina 10.15.1 on my existing system, to 10.15.1 on my new one.
What do you need to copy/back up first?
As we’ll be re-installing all our programs and dev environment from scratch, the only thing we need apart from the installers for our programs, is a copy of our files and data. For most of us, these are located in our home directory. So for instance on my mine this is Macintosh HD > Users > Aston, making
Aston my home directory. It’s the contents of this that I’ll need to backup as per the instructions below.
First make sure hidden files are switched on first, in the terminal type:
Then simply plug in your external HD, create a folder called
Home Directory Backup then drag the contents of your home folder into it.
While you could restore files from a Time Machine backup directly, I prefer to do straight forward copying because I’ve experienced ACL permission problems when restoring files from a Time Machine backup previously. Plus straight-forward copying is considerably faster.
I personally use iCloud for the Notes, Calendar and Contacts apps (as well as for Safari bookmarks) because I have an iPhone and it’s just really handy having them automatically synced. If you do the same you won’t need to worry about transferring their data to your new Mac/install as they will get synced afterwards.
Make a note of your passwords
For some reason Apple have made it practically impossible to transfer the passwords stored in your ‘local items’ keychain (this is the keychain that they use for iCloud passwords). So go to the Keychain app (CMD Space and type ‘Keychain’) and make a note of any passwords you need from the
local items keychain (you don’t need to make a note of items in your
login keychain as we’ll be copying them over later). Just right click and ‘show password’. Tip: If you want your Safari passwords, you can simply go to Preferences > Passwords then select all and take screen grabs of them (then put them into a password protected PDF).
Make a note of your email passwords while there just in case you need them, they’ve always worked for me but newer ones might be stored in ‘local items’.
Once everything is backed up
You can begin the install of macOS onto your machine – if you are reinstalling onto your original/only computer double check you have ALL of your files backed up or copied onto an external drive because you will be wiping your computer’s drive clean!
Create a bootable installer for macOS
Use this guide to create a bootable installer: https://support.apple.com/en-us/HT201372
Time to install macOS!
Insert the USB drive and restart your Mac, but hold down CMD and R (on older Macs you might need to hold down the ALT key instead)
If you have a newer version of macOS it will ask you to type in the password of an existing account. Then…
- Go to Disk Utilities
- From the ‘View’ menu select ‘Show All Devices’
- Select the disk you want to install macOS on to
- Select APFS and GUID Partition Map (don’t select encrypted, we’ll do that later)
- Give it a name (most people use ‘Macintosh HD’)
- If you want to securely delete what’s already on there choose the option in ‘security options’ (Not needed if your previous install was encrypted)
- Click ‘erase’
- Once done close the window
- Back in the main options screen select Reinstall Mac OS X
Then follow the instructions to set it up. To make life easier I use the same user account name and password as my previous install. Then once it has installed…
Change your account name, turn on Firewall, install LittleSnitch and turn off wake from sleep for network activity
Firstly, DO NOT open the MAIL app until after we have restored all of our mail settings!
- Apple now prefers to use lowercase for account names but if you’re like me, and prefer to capitalise the first letter of your name go to System Prefs > Users & Groups > click on lock to make changes > right click you user account > Advanced, then from here change location of Home directory (so mine is /Users/Aston) then after it restarts in finder navigate to /Users/yourname and change it to /Users/Yourname.
- For some odd reason the Firewall isn’t on by default, so go to System Prefs > Security and Privacy to turn it on.
- Install LittleSnitch if you like to control network activity for your programs.
- Then if you don’t want your Mac to wake from sleep because of network activity, turn it off via System prefs > energy saver > uncheck wake for network access
Time to put back your files, keychain and mail
Now that you’ve backed up all your important files and done a clean install, it’s time to put back all your important stuff, such as:
- Keychains & passwords
- /.ssh folder and other important invisible files
First, make sure hidden files are switched on, in the terminal type:
Navigate to the
/.Library/Keychains folder on your backup and copy the
login.keychain and call it something like
old-login.keychain. Then copy it to your new /.Library/Keychains folder.
Open the Keychain Access app (CMD and SPACE, then type ‘keychain’). Then go to
File > Add Keychain from the menu and select the old-login keychain.
Now we want to copy everything from the old-login keychain into the new login one. However normally when copying keychain items from one to the other, Keychain Access will ask you for your password for every item – but that would be a huge pain!!!
Right click the old-login keychain and select ‘set new password’. Put in the original password for it in the first field, but leave the new password fields empty. It will complain that the new password is not secure enough but you can just override this by holding the Option key and clicking OK.
Now go through the list of items and CMD click the ones you want to transfer (I usually just transfer internet passwords etc – leaving out application passwords, public keys, HD volume passwords, certificates, etc). Once you’ve selected what you want, drag them over to your new keychain and click allow whenever it asks (much better than having to type a password each time).
Once done, simply delete the old-login keychain.
Copy these (or the contents from them) from your backup to the same places on your new install:
RESTART YOUR MACHINE
Once your machine has restarted it is ok to open Apple Mail – all your email accounts and emails should be present, however if any of your passwords were in the ‘local items’ keychain you may need to enter them again (go to Preferences > Accounts > Server Settings and check there are passwords present – if not, add them manually).
Hidden files, folders and fonts
/.ssh folder from your backup to the root of your new home folder.
Repeat for any other hidden files you need, such as the
.gemrc etc. (I recommend copying program specific files AFTER you have installed them, such as .gvimrc, .gitconfig, .vim/colors directory, etc.)
Copy or double click any fonts you want installed on your new system, from
/.Library/Fonts on your backup to the same on you new install.
Restoring the rest of the home directory and installing your other programs
Now the easy part!
You can now move all your other files from the backup to the new install. Personally if a folder already exists (such as the Music, Movies, Documents, Downloads, Desktop folders etc) I move the contents of the folder into it rather than trying to overwrite it. Your custom/non-standard folders can just be copied over.
Once that’s done, you can then install all your programs as normal.
There you have it, a nice, fresh start!