Setting Up a Time Machine Drive from the Command Line
It’s possible to set up Time Machine drives from the command line. This is way more convenient and becomes scriptable (there’s one GUI checkbox at the end if you encrypt, so the drive can unlock itself). Also, based on my own personal experience, the Time Machine GUI can be unresponsive so the CLI is much better. I’ll be using a 1TB external SSD in this guide. Here’s how you set up a drive. Some of these terminal commands require Full Disk Access. Specifically, the commands we’ll be using later on. Grant your preferred terminal app full disk access in System Settings -> Privacy & Security -> Full Disk Access. Plug in your drive. Unlock it if you have to. Run the following to get some information we’ll need. Here is what you’ll see if the drive is currently being used for Time Machine: Here is what you’ll see if the drive is brand new: Two identifiers matter here: Confirm that you have the correct disk with this command. We know this one is the external drive due to the line. On Apple silicon the internal drive shows and . We’ll need to erase the disk next. The steps vary slightly depending on whether the drive is brand new or is an existing Time Machine drive. New drives usually ship as ExFAT with an MBR partition scheme, so there’s no APFS container yet. We can erase and convert the disk with this command: This results in a drive with a GPT scheme, an EFI partition, and an APFS container with one volume in it (read more on containers vs volumes in APFS: Containers and Volumes ). It does not encrypt the volume, enable ownership, or set the Time Machine role, which are all things we need. So we’ll delete this newly created volume and create a proper one later. Run this again to figure out the identifier: The identifier is in this case. Now use that identifier to delete the volume that was created in the step: That’s it for this section. Skip ahead to the “Create the Volume” section. If the drive is already being used for Time Machine we need to remove the destination (the disk entry in the Time Machine GUI). First, figure out the destination UUID: Then remove the old destination. We’re using so it’ll prompt you for your machine’s password. Verify it’s gone: You can double check that this worked by checking in System Settings -> General -> Time Machine. There should be no backup drive listed. If it’s still there, you can manually remove it in the GUI. Now delete the old volume. The container stays, so there’s no need to repartition the whole disk: If you get an error like: That’s Spotlight. Removing the Time Machine destination makes macOS stop treating the drive as a backup target, so Spotlight starts indexing it like any other volume and holds it open. Turn indexing off for that volume and try again: Now that the external drive has been erased, we need to create an APFS volume on the drive. Decide if you want your backups to be unencrypted or encrypted and follow the corresponding steps. Note that this only worked for me with the flag in the commands. Do not leave it out! If you skip this option, macOS deletes the volume you just created and builds its own in its place when you register the drive in a later step. It has to do with APFS volume roles. The role is for Time Machine backup stores. You can read more about these roles here: How do APFS volume roles work? . Run the following command to create a volume without encryption: Run the following command. It’ll prompt you for a password for your drive. Run this to confirm everything went well. Under you’ll see if it’s an encrypted volume. You’ll see if it’s an unencrypted volume. Two things to note here: Time Machine refuses any destination that doesn’t enforce file ownership. It can’t preserve the UID or GID of what it backs up without file ownership. Volumes created from the command line have it turned off by default. Run the following to enable ownership, replacing the path with your own external drive’s path: Run the following to double check that it worked. should be : “Registering” means telling Time Machine to use this volume as a backup destination. It’s what the GUI’s “Add Backup Disk” button does. The button and the command we’re going to run both write to . Run the following to register your drive: No output means it worked. appends to your destination list rather than replacing it. If you run into this error, try waiting a bit and then try again: Then run these commands to double check everything went well: The output containing confirms that a destination exists and its volume is reachable. Confirm it points at your volume and not a replacement: That UUID should match the one from earlier. If it doesn’t, macOS replaced your volume with one of its own, which is what happens when the flag gets left out. We can add paths we want to exclude from backups through the command line too. There are three kinds of exclusions: fixed-path exclusions, sticky exclusions, and volume exclusions. But for our purposes we only care about fixed-path and sticky exclusions. Here’s an example of adding a fixed-path exclusion: Here’s an example of adding a sticky exclusion (same command without the this time): Check any path to make sure it was added to the exclusions. You should see next to the path (If you see that means no file or directory is there, not that the exclusion didn’t register): To list fixed-path exclusions we need to read them out of the preferences plist: Sticky exclusions don’t appear in the preferences and are stored as an extended attribute on the item: Removing them is similar to adding. We use instead. The flag is still necessary for removing fixed-path exclusions but not for sticky exclusions. Here’s an example of how to remove a fixed-path exclusion: And here’s an example of how to remove a sticky exclusion: Try manually starting a backup through the command line: The command above may look like it’s stuck if your backup takes a while. You can run this in a separate terminal tab/window to monitor its progress: If you get an error like: That just means macOS started a backup automatically. Once it’s done you can verify with: The path in the output confirms that a real backup exists. You can also check the result code: means the backup was successful. Anything else means the last backup failed. This only applies to encrypted drives. From what I can tell, there’s no way to store the Time Machine drive’s passphrase in Apple Keychain using the command line. If you prefer your drive to unlock automatically when it’s plugged into your machine, you’ll need to do the following. Eject the drive (change the path name to your drive’s): Plug it back in. When the password dialog appears, type the passphrase and check “Remember this password.” That’ll save the passphrase in your local keychain so that macOS can unlock the drive automatically next time you plug it in. No need to type in the passphrase every time. Confirm it worked by ejecting and replugging once more. If you aren’t prompted to type in your passphrase, that means it worked. You can double check via the command line too: If is present, that means the drive unlocked and mounted. If you go through this process a few times there’s a good chance you’ll have several Keychain entries for old Time Machine drives. Deleting a volume doesn’t remove its Keychain entry, you’ll have to do this manually. Normally, these Keychain entries point at volumes. But since those volumes were deleted, the entries are pointing at volumes that no longer exist. We can run the following to list all relevant Keychain entries: There’s two entries. To find the one that actually points to a volume, run: So UUID points to a volume. Which means UUID is safe to delete. We can delete it like so: We can then double check that we only have the necessary Keychain entries left: However, this is just for the sake of being tidy. I don’t think having these kinds of entries in Keychain affects macOS negatively in a significant way. — the whole physical disk. We’ll need this later on when running the command. — the APFS container. This is what we’ll need for the command. (A brand new drive won’t have this one yet. It’ll get created when we erase the disk in a later step.) The volume identifier won’t always be , APFS reuses freed slots so yours may be something like or . Write down the volume UUID, we’ll need it later on to verify everything works. Fixed-path exclusions are tied to a path regardless of what is there. Use these exclusions for anything that gets deleted and recreated, like build caches. Sticky exclusions are the default. They’re tied to the item itself. It follows the file if you move it and copies inherit it. Deleting and recreating a directory loses its stickiness. https://support.apple.com/guide/mac-help/back-up-your-mac-with-time-machine-mh35860/mac https://keith.github.io/xcode-man-pages/diskutil.8.html https://keith.github.io/xcode-man-pages/tmutil.8.html https://eclecticlight.co/2024/11/21/how-do-apfs-volume-roles-work/ https://eclecticlight.co/2024/04/02/apfs-containers-and-volumes/ https://eclecticlight.co/2021/10/12/juggling-with-hfs-and-apfs-partitions-and-volumes-a-primer/
HTML
Shell
Programming
Tutorial
DevOps
Ruby
Cloud
CSS
Career
Business
Go
AI
C#
Python
Web Development
Performance
Security
Git