macOS Sierra's Documents in iCloud feature can cause data loss

The latest version of macOS introduced a feature that stores your Documents and Desktop folders in iCloud. This causes a number of problems with Anki (among other apps), so if you are not already using Anki 2.0.40+, we strongly recommend backing up your Anki data and then upgrading to the latest Anki, which moves the Anki files outside of iCloud.

Checking if your Documents folder is in iCloud

• Click the Apple icon at the top left of the screen and choose System Preferences.
• Click the iCloud button.
• Click 'Options' next to iCloud Drive.
• Check if 'Desktop & Documents Folders' is deselected.

If 'Desktop & Documents Folders' was not selected, or iCloud drive was not on at all, it is safe to upgrade to the latest Anki version without any extra work.

If 'Desktop & Documents Folders' was selected, iCloud may have deleted some data from your computer once it was placed in iCloud. So you'll need to follow the steps below to make sure nothing is lost.

Backing up your data

Your Anki data is currently stored in your Documents/Anki folder. We'll be moving that entire folder to somewhere outside iCloud, which will download anything that is missing.

• Make sure Anki is closed
• Open Finder
• Hold down the option key on your keyboard, and click on the Go menu at the top of the screen
• Select 'Library', and your Library folder will open. The Library folder will not appear unless you are holding down the option key.
• Locate "Application Support", and open it.
• Check if an "Anki" folder exists. If it does, it is from a very old version of Anki. Please use the File menu, then Rename in order to rename it to something like "Anki-old"
• Check if an "Anki2" folder exists. If it does, it indicates you've already upgraded Anki. Please skip the rest of these steps and copy your Documents/Anki folder somewhere else in case you need it in the future.

Next, while Application Support is still visible:

• From the File menu, select New Tab
• Open your Documents folder, and locate the Anki folder
• Drag the Anki folder onto the Application Support tab, which will move it and download any files that were only on iCloud Drive
• Return to the Application Support tab, and locate the Anki folder
• From the File menu, select Rename, and call it "Anki2"

Upgrading Anki

It is now safe to upgrade Anki. When you start it, it will automatically locate the files in the new location.

Recovering from data loss

• If your cards have disappeared but they are still on AnkiWeb, you can sync and choose Download. If your cards are not on AnkiWeb, you may be able to restore from an automatic backup: http://ankisrs.net/docs/manual.html#backups

• If sounds and images have gone missing, you may still be able to locate them if they're in iCloud's Documents folder. If they're there, you can copy them across to the new Anki folder's collection.media folder.

More info for the technically inclined

• Files that are stored in the cloud but not on the local machine - such as when 'optimize storage' is on, or when the files were added on another machine and have not been downloaded yet - are invisible to Anki. If your collection file is missing when Anki is started, it'll create a new one, and that will end up being uploaded to iCloud, overwriting your cards.

• Anki will not be able to show any sounds or image files that have been 'optimized' (ie, are missing from the local machine). Worse yet, if they were previously in your collection.media folder and have since disappeared, Anki sees that they have been deleted and will delete them from AnkiWeb on a subsequent sync, as it has no way of telling that the files were removed by iCloud and not the user. This can result in sound and image files being removed from your other devices as well. The files should still be iCloud, and Anki will be able to use them again once you download them.

• When more than one Mac is added to iCloud, macOS renames your documents folder to "Documents - [computername]". This can cause Anki to no longer find your files, as it expects the Anki folder to be in the top level of Documents.