Home > Mac administration, macOS > iCloud Desktop and Documents in macOS Sierra – The Good, The Bad and the Ugly

iCloud Desktop and Documents in macOS Sierra – The Good, The Bad and the Ugly

As part of the iCloud services in macOS Sierra, Apple is offering a new way to store your files in iCloud – synchronizing the contents of your account’s Desktop and Documents folder with iCloud Drive.

LWScreenShot 2016 09 20 at 7 34 49 AM

When you enable the option to store files from your Desktop and Documents folder, the contents of your Desktop and Documents folder are moved (not copied) from your home folder into iCloud Drive. Those folders will no longer appear in your home folder.

Screen Shot 2016 09 16 at 9 21 48 PM


That means that your Desktop and Documents folder no longer are stored in your home folder. Instead, they and all their contents are now stored in iCloud Drive.

Screen Shot 2016 09 16 at 9 39 40 PM

Screen Shot 2016 09 16 at 9 20 39 PM

For more details on this, see below the jump.

In reality, the Desktop and Documents folders folders themselves have been moved to a new location inside your home folder, where they’re invisible to the average user but still provide a place to sync files between the Mac and iCloud Drive. The new location is as follows:

~/Library/Mobile Documents/com~apple~CloudDocs

Screen Shot 2016 09 20 at 11 01 28 AM


The Good

The virtue of this idea is that, as you enable iCloud Desktop and Documents on your various Macs, you get a unified Desktop and Documents experience. As you add files to those directories on one machine, all of your other machines should get updated with the same information. You can also access the files from the iCloud web interface and the iCloud Drive app on your iOS devices, in the event that you’re away from your Mac(s) and need to get something that is stored in the Desktop or Documents folders on your Mac(s).

Screen Shot 2016 09 16 at 9 36 16 PM

Screen Shot 2016 09 16 at 9 36 24 PM


iCloud in this sense is serving as the authoritative source of “truth” for your files and your various Macs are checking in and updating files on themselves as needed. When all of this works, it looks like magic and all your files are everywhere you need them.

When all of this works. What happens when it doesn’t?


The Bad

Currently, Apple provides 5 GBs of storage space for free for iCloud users. That 5 GBs of storage includes storage for your iCloud email, your iCloud backups for your iOS device(s), your iCloud Photo library and iCloud Drive. If you need more than 5GBs of storage space, you have to pay for it.

Screen Shot 2016 09 16 at 8 55 23 PM


Considering that most folks likely have more than 5 GBs of files stored in their home folder’s Documents directory, let alone their Desktop folder, there are immediate issues with enabling iCloud Desktop and Documents syncing if you’re not paying Apple for sufficient iCloud storage space.

As an example of this, lets try adding a VMware VM to the Documents folder then turn on iCloud Desktop and Documents syncing.

VM is 11.55 GBs in size
Available iCloud space is 5 GBs

Screen Shot 2016 09 20 at 11 12 32 AM

Screen Shot 2016 09 16 at 9 20 13 PM


I immediately ran out of space on iCloud Drive and was prompted to upgrade.

Screen Shot 2016 09 20 at 11 08 02 AM


To its credit, iCloud was smart enough to figure this out before it tried to upload the VM and did not actually try to upload the VM to iCloud Drive. It also allowed me to move the VM unharmed to a new location.

Screen Shot 2016 09 20 at 11 10 54 AM


The Ugly

At this point in my testing, I decided that iCloud Desktop and Documents was interesting but because of storage limitations, it just wasn’t going to work well for me unless I paid Apple far more money for storage than I wanted to. I then did the following:

1. Opened System Preferences
2. Selected the iCloud preference pane

Screen Shot 2016 09 16 at 8 55 16 PM

3. Clicked the Options… button next to iCloud Drive

Screen Shot 2016 09 16 at 8 55 24 PM

4. Unchecked Desktop & Documents Folder

Screen Shot 2016 09 16 at 10 04 36 PM

At this point, I received a warning that the documents on my Desktop and in my Documents folder would only be visible in iCloud Drive.

Screen Shot 2016 09 16 at 9 45 24 PM


5. Clicked the Turn Off button on the warning dialog message.

Screen Shot 2016 09 16 at 9 45 50 PM


At this point, I received a message letting me know that my documents are in the Desktop and Documents folders in iCloud Drive and that I could copy or move them back.

Screen Shot 2016 09 16 at 9 46 30 PM


6. Clicked the OK button on the message.

Screen Shot 2016 09 16 at 9 46 31 PM

Sierra then showed me that my Desktop and Documents folders were back in my account’s home folder. Great!

Screen Shot 2016 09 16 at 9 47 03 PM


They were completely empty. What!?!?!?!

Screen Shot 2016 09 16 at 9 49 37 PM

Screen Shot 2016 09 16 at 9 49 59 PM


When you turn off the Desktop & Documents Folder feature in iCloud, Sierra recreates empty Desktop and Documents folders in your home folder. It’s on you to copy or move your files back from iCloud Drive.

However, that assumes that all of your files and folders made it to iCloud in the first place. What if they didn’t? Hopefully they can still be found in the Desktop and Documents folders in ~/Library/Mobile Documents/com~apple~CloudDocs.

Screen Shot 2016 09 20 at 11 01 28 AM

If they’re not, hope you had other backups because those files and folders may just be completely gone.


Based on the results of my testing, I have no plans for enabling iCloud Desktop and Documents syncing on any of my Macs for the foreseeable future. Leaving aside that Apple isn’t offering enough storage space at prices I want to pay, the results I saw from my testing of the synchronization process did not inspire my trust in it.

It did give me an insight into why Apple chose to remove support for portable home directories (PHDs) in Sierra. The havoc that could be caused by two separate synchronization processes trying to sync the same set of files, especially when portable home directories were using a two-way sync process, would be breathtaking to behold. The only certain result would be that data loss would occur. Kudos to Apple for at least foreseeing that result and removing the possibility of PHDs and iCloud Desktop and Documents fighting with each other for file sync supremacy.

For those Mac admins that want to block iCloud Desktop and Documents in their own environments, please see the post linked below:


Categories: Mac administration, macOS
  1. Alex
    September 23, 2016 at 5:03 pm

    I made that mistake and even went as far as buying more room but once I found out that it chewed through a lot of data and slowed everything else down from (slow internet) downloading while uploading I decided it wasn’t worth it and downgraded my storage back to what it was before and started looking for the files. I eventually found them in ~/Library/iCloud Drive (Archive) and moved them back.

    Great way of Apple to increase their revenues having people purchase more room to store the Desktop and Documents Folder on their servers.

  2. Alex
    September 23, 2016 at 5:09 pm

    So far I have found running Sierra like running El Capitan except I am not sure what Apple did to the Preview.app. I use to be able to fill out .pdfs and save them and email them back to person that created them for contractor work and they had no problem reading them, but now I fill them out and send them back and the only thing the other party sees is the signature and nothing else. Luckily I didn’t update my MacBook Air and will have to use that until Apple comes up with a fix to this problem.

  3. September 24, 2016 at 5:08 am

    So actually the Desktop and Documents DON’T get moved, but get symlinked into the com.apple.clouddocs folder and then the original location gets hidden?

    When turning off iCloud doc and desktop sync, Apple should just leave the files where they are and turn off their hiding and advising you of such — Like when they give you the option to keep local copies of contacts etc when you turn off the iCloud feature for that feature.

    I don’t quite understand why they get hidden anyhow, when they actually don’t get moved.

    • Guest
      September 24, 2016 at 12:20 pm

      The solution does seem unusually messy. The command-line interface is not fooled and can see that ~/Documents and ~/Desktop still exist. What Finder does is simply window-dressing, obscuring the reality from the user. They did not even bother to use the Unix file flags to hide the directories (like they do with the user library), but deployed a new extended attribute instead, meaning that only Finder can work with this.

      It baffles me even more that Apple decided to move existing documents upon disabling iCloud Drive into the above-mentioned ‘~/Library/iCloud Drive (Archive)’, even though they are technically located in ~/Documents and ~/Desktop while iCloud Drive is active. Given that ~/Library is hidden by default, I suspect that this will raise even more questions.

      All around a poor job. I expected that this new feature would be trouble, the moment they announced it.

  4. Daniel O'Donnell
    September 26, 2016 at 4:43 pm

    Good summary of the problem(s) and how to deal with them.

  5. dpodgors@amfam.com
    September 26, 2016 at 7:03 pm

    So under configuration profile in restrictions, under the functionality tab, why wouldn’t just uncheck “Allow iCloud documents & data”?

  6. Stephan
    September 27, 2016 at 6:18 pm

    Linked by Gruber at Daring Fireball. Nice job Rich!

  7. September 27, 2016 at 6:31 pm

    As someone else has pointed out it is worth clarifying that the Desktop and Documents folder do not actually get moved, they remain in the user’s home directory /Users// but are hidden by the Finder. The entries you found in ~/Library/Mobile Documents/com~apple~CloudDocs/ are just symbolic links to the real, unchanged, locations of those folders.

  8. September 27, 2016 at 10:13 pm

    Alex – as far as your PDF problem is concerned. If the PDF was created using a any Fujitsu Scansnap, it will destroy your existing PDF Files in the manner you describe. They issued several warnings not to upgrade as it might ruin existing PDF files. See http://www.fujitsu.com/global/products/computing/peripheral/scanners/topics/topics20160926.html

  9. Sigivald
    September 27, 2016 at 10:51 pm

    Considering that most folks likely have more than 5 GBs of files stored in their home folder’s Documents directory, let alone their Desktop folder

    I think you might be overestimating what “most folks” do with their computers, especially those directories (where, say, iTunes media aren’t).

    Power users and developers, sure, that being “most of the people you’d have to ask about this or reading this right now”.

    But most folks don’t – I think – even know what VMWare is, for instance.

    “Joe Macbook User”, though, might have a gig of school or work files, maybe. Some memes they saved off of Facebook (maybe – lots of people seem to just Share them to “save” them). Perhaps an app installer or three lying around on the Desktop (or not, if they just use the App Store, which is very likely).

    5 GB is actually a lot of space for non-media files for a whole lot of users.

    • Jiří Fiala
      October 1, 2016 at 10:07 pm

      On the contrary – non-technical users have no idea what they put where, nor how much space is occupied or how to find out. When I fix my friends’ Macs, in routinely able to salvage tens of gigs of space without deleting something of value.

  10. Roger Dodger
    September 28, 2016 at 3:13 am

    In my experience with Beta and after beta, turning off Desktop and Documents Folder syncing with iCloud leaves a folder in ~/iCloud Drive (Archive), not in ~/Library. Not sure if I misunderstood or mis-read. All items were there though.

  11. Jeff Willner
    September 28, 2016 at 7:03 pm

    Even though I had more than enough space on iCloud, I had tons of problems (and error messages) trying to copy my files back from iCloud to my computer after turning off iCloud desktop and docs. Finally gave up and restored from a backup I created just before enabling the feature.

    Not sure that I will ever trust iCloud as the repository for anything that is important to me.

  12. October 1, 2016 at 10:01 am

    any idea how to make the Desktop and Documents folders visible in Finder? I’m intelligent enough to understand they are in iCloud, I just don’t like having half my stuff in the home folder window and my other half in the iCloud folder, and therefore I have to open two finder windows.

    So far I’ve created symlinks but I don’t like that approach!

  13. fly
    October 6, 2016 at 8:27 am

    I don’t suppose there is a way to view the contents of the Mobile Documents folder in finder??? SO annoying Apple. Thanks.

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: