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.

  14. Paul Coppens
    October 23, 2016 at 1:03 pm

    Same problem here. I switched it on at some point then realising I didn’t have enough space. Didn’t want to buy more than 5 GB. Switched it off again and then got the message needed to upload all before able to switch off. But I had 60 GB. Was able to switch off after all after downloading my docs again to my Mac. However it seems my 5 GB is still full and my folder on my Mac (iCloud Drive) is empty. Not sure now how I am able to release the bigger part of my 5 GB.

  15. Em Raisun
    October 25, 2016 at 9:33 am

    Oh my god, I switched off the cloud sharing and it stole my desktop. Then I went to iCloud in Finder to retrieve my desktop and all the folders are there but they’re empty.

    I want to cry. What do I do now? My time machine wasn’t on either.

  16. Martin Andersen
    November 23, 2016 at 2:10 pm

    I don’t understand the usage of the folder Mobile Documents. I have turned off Desktop & Documents Folders. When I view info on the Mobile Documents folder, it says the size is 460 GB and if I double clicks the folder, it takes me to the iCloud Drive. It looks like it is just at short cut to the iCloud Drive, but it still fills up 460 GB on my local hard drive.

    • James V
      April 7, 2017 at 9:14 am

      When I select Get Info on my Mobile Documents folder I see, 30,690,420,655 bytes (2.45 GB on disk) for 26,120 items. I haven’t turned on the Desktop & Documents option, but I have selected Optimize Mac Storage. So out of the 30GB I have stored in iCloud Drive, only 2.45GB are actually stored on the local drive—the rest are still in the cloud, indicated by the Cloud icon with the down arrow next to each item. But how is it you have 460GB in iCloud? I thought the most storage offered was 200GB?

    • James V
      April 7, 2017 at 9:19 am

      I should add that I did this on a new computer. Rather than having all the files originally on my Mac, the files are originating from iCloud.

  17. December 8, 2016 at 10:12 am

    I have sierra and have disabled the icloud syncing and the various options as above but all the docx have disappeared from finder and all desktops including icloud drive – but if i do a search im told they are on the mac in the icloud (archive) desktop – but when I look at the desktop folder in icloud it is completely empty – so how do I see this in finder

    the desktop and document folders in icloud drive are both empty

    how do i access this archive in finder – this is such rubbish

    • December 8, 2016 at 10:51 am

      Search for your files (as you say you have done), then press command-R to reveal the file in its originating folder. You could then press command-uparrow to go the folder above and move it somewhere more useful.

      • December 8, 2016 at 2:12 pm

        Thank you – that is helpful except that I would like ALL the files that are in the archive restored – I dont want to have to do a search each time but just go to finder and there they are – any ideas – id get rid of icloud if i could be sure that nothing will be lost – if I knew how to do that too

      • December 8, 2016 at 2:33 pm

        Take my idea to its logical progression and work you way up the folders until you find your entire old desktop folder. Move that folder somewhere where you then know how to find it.

      • December 8, 2016 at 2:56 pm

        There are no folders only 2600 files – when i look at icloud in finder and do a search the desktop is highlighted yet none are on the desktop where there are two folders docs and desktop they contain none of these files
        – when I do cmd R I see from reading at the bottom of the screen giving the location
        eg, desktop or icloud archive or direct under icloud
        there must be a way of restoring them all out of the cloud and back to their original place – cant do this 2600 times Ill lose the will to live!
        how can we unhide the desktop and doc folders
        i have managed to move just a few by opening them in word for instance and saving to desktop but each time it says do i want to overwrite – well although I say yes – I cant see what i am overwriting

        once this is all done can il get rid of icloud all together I think – is it all a result of Sierra? as I never had this before

        thanks for help

      • Marion Hebblethwaite
        December 8, 2016 at 3:17 pm

        there is also something strange happening – any file which i have somehow managed to move to be visible on the desktop now has this a overprinted on it – does this mean it has been archived?

        I have been using computers since 1994 and pretty Ok with most things but this problem with Sierra and Icloud has taken on another dimension – the missing files are also mainly docx – so I wonder now if this is a Sierra/Icloud/Word problem



    • December 8, 2016 at 11:14 pm

      Hi Marion, far be it from me to describe what this blog is for, but I don’t think it is for end-user technical support as such. Obviously not being the author, I am open to be corrected, but this blog’s audience is mostly Mac Systems Administrators and those with certain experience administering large quantities of Apple Macs in business and corporate and education environments.

      I’ll just offer one last thing — If you are able to ‘see’, find or otherwise access those 2600 files, despite them being not where you’d like them to be, then there are myriad of ways to then move them to where you want them to be. You might wish to book an Apple genius or consultant in your area to assist with this.

      • Marion Hebblethwaite
        December 9, 2016 at 7:33 am

        thank you – I didnt realise that was the purpose of the blog – I found it through the search I was looking for

        thank you for your help – will do as you suggest Mari

  18. December 8, 2016 at 10:53 am

    Rich, are you able to update your article so it is correct? The Desktop and Documents folders do not get moved, as you have written, but get hidden and then symlinked into the iCloud drive structure.

    • Susan Johnson
      December 10, 2016 at 5:19 pm

      I would also personally love some clarification on the best way to proceed to get your files back in place9, once you’ve activated this feature, and want to safely deactivate it. Based on these comments, it sounds like just turning it off and hoping everything is still in iCloud, waiting for re-downloading is a bit unreliable. Is there a best practice for reversing this clusterf***, once you’ve stumbled into it? I wish I’d found this page first…

  19. Paulo
    December 20, 2016 at 8:46 pm

    when I select the option to synchronize the documents and desktop folders, it is in the loading state but never ends. Then I enter my iCloud account from the web and the carpets do not exist. Help me, am I doing wrong?

  20. Ivar
    December 21, 2016 at 7:56 am

    This may be helpful to non pros like me, to turn this damn thing off (iCloud Drive) and restore desktop and dokument folders…

    • Ivar
      December 21, 2016 at 8:06 am

      As described earlier, the Desktop and Document folders are to be found in Finder; simply open the window “iCloud Drive” and the open another window “Desktop” and yet another “Documents”, then drag the folder back to where they belong!!

    • Susan Johnson
      December 21, 2016 at 3:52 pm

      Yeah, I ended up just turning the damn thing off and using Google Drive for specific folders. iCloud was not only clugy and unpredictable, I also found that it was eating up my bandwidth at all hours of the day. Not good.

  21. Randy
    February 17, 2017 at 9:48 pm

    I thought a ‘feature’ of iCloud Drive was to move unused documents from a Mac’s hard drive to iCloud when space became an issue. If the files are still on the hard drive, how is space freed up? Are the archived files on the Mac then compressed?

  22. Bern Shanfield
    March 31, 2017 at 6:04 pm

    This is from Apple’s support page: https://support.apple.com/en-us/HT206985

    “Turn off Desktop and Documents

    When you turn off Desktop and Documents, your files stay in iCloud Drive and a new folder is created on your Mac. You can move files from iCloud Drive to your Mac as you need them, or select all of your files and drag them to the place you want to keep them.
    From your Mac, go to Apple menu > System Preferences > iCloud.
    Next to iCloud Drive, click Options.
    Deselect Desktop & Documents Folders.
    Click Done.”

    Does this not work?

  23. Petra Schoep
    June 2, 2017 at 2:43 pm

    Really glad I found this page before I started using my brandnew iMac with Sierra installed. My document folder on old iMac is 10GB! Turned off desktop and documents in new iMac, and manually put desktop items in now visible desktop folder. Now I will transfer all my documents into the doc folder in my home folder. I back up with Time Machine and will let iCloud go for now….

    • Jesus Valdez
      June 18, 2017 at 3:18 am

      I wasn’t so lucky. our iMac is logged onto my wife’s iCloud account and now 85GB are uploading to the cloud and pulled off our hard drive. I do have time machine with the airport, but wow. I didn’t know it would take all the files off my hard drive. It looks like by clicking the cloud icon in Finder with control click, it will download the “my documents’ folder again. We do have family sharing, but I’m worried now i always have to be signed into her iCloud account or I will never see my documents again. wondering if family sharing will work.

  24. July 7, 2017 at 6:47 am

    IF you experience lost files when disabling the iCloud documents feature, timemachne has your back. The folders are restorable from backup.

  25. melva evans
    August 8, 2017 at 5:45 pm

    I was on the “chat” phone with apple for 3 hours yesterday, trying to figure out WHAT happened to all of my husbands icons..i updated his mac, and they disappeared….
    I am still in a mess, but this article is exactly what happened. the only difference was that the geek guy, told me to drag the files…(when we found them) into the iMac (on the icloud drive) when i did that, it transferred them to my retina laptop…so then he told me something else to do that should get them back to my husbands mac. it didn’t seem right to me, so i just gave it up…missed dinner, had to go to the bathroom etc.,..My husband is so mad at me/day ruined.
    So today, this article helped so much!…i live to try again!!!

  26. Michael Ford
    September 1, 2017 at 12:49 am

    It does help me when I don’t have a computer to download the app on only a apple iPhone 6 and my iPhone 5SE is blocket and it’s going to taken 3 working days and nights before i get the help I need but I can’t afford the money they are asking for for the toolkit to unblocked my iPhone so I will just wait until I get ether a text or email from Apple company with the correct password and email to unblocked my iPhone that cost me £200 hundred pounds from a electronic shop that fixes computer and phones

  27. September 6, 2017 at 3:24 am

    Thank you for explaining this. I cannot/could not believe that my most basic questions about iCloud weren’t clearly explained somewhere easy to find — e.g. What happens to the things I sync when I turn on iCloud and, importantly, what happens to them when I turn it off? I was afraid to turn it off and so dealt with ridiculous slowdowns on my computer until the IT folks at work figured out the problem and turned off iCloud for me, and made the iCloud Archive.

    But one thing happened that seems to contradict what is said above. After turning off iCloud, my documents are still on iCloud AND on my machine (in the newly-created “iCloud Archive” folder). I’m assuming that I need to manually move the folders from there to wherever I want them. BUT, I have a weird ‘documents’ folder in the usual place, but it can’t be deleted….

  28. Karthikeyan
    October 17, 2017 at 10:56 am


    Any idea how do they link the Documents and Desktop (like Documents -> /Users/kam/Documents) ? Hardlink is removed in High Sierra but I can see its a link with Documents -> /Users/kam/Documents. Any command line or framework to achieve this? Thank you

  29. Dave
    November 11, 2017 at 3:44 pm

    I guess one way to quickly access your Documents and Desktop folders it to create aliases for them, and place those aliases on your desktop, in your Home folder, and other locations in the file hierarchy. This lets you see what’s there and use those locations, but I think it also lets you have all the advantages conferred by cloud-based storage.

  30. Dave
    November 11, 2017 at 4:00 pm

    Between iCloud, my iMac’s hard disk and my Time Machine, it is getting harder to understand the structure of the file system and the relationships between the different storage media. There is a primary version of every file I create somewhere on my iMac’s HD, and accessible copies on other media connected wirelessly to my iMac. I wish Apple would create a utility that lets you see these relationships graphically, similar to the way AirPort Utility lets you see other devices on a WiFi network. It could show you how and when synchronizations happen, where the primary copies and the back-up versions are, what compression and encryption is used, how much capacity you have in each medium or device, etc., and maybe other what devices such as tablets and smart phones that occasionally access these media. All these connections and transfers are currently pretty much hidden most of the time and users have no way to see what really goes on behind the big curtain drawn over them by Apple. A utility like this would give MacOs users far higher confidence in the integrity and security of their precious files.

  31. Michael Kay
    February 14, 2018 at 2:37 pm

    I plan on disabling this using a config profile in JAMF, but how can I find via command line or script whether Desktop and Documents syncing is actually enabled? Only thing I have been able to do so far is see whether the iCloud Drive service is enable or disabled.

  32. March 6, 2018 at 3:07 pm

    Wonderfully outlined. I had the same issue.
    And was shocked when my desktop & documents DISSAPEARED, from my Mac’s desktop and documents locations!!
    I’m still looking for the mobile folder you mentioned, but I’m not pleased with Apple for not mentioning this would happen, nor creating a support page on how / where to retrieve the data

    • mikemac52@gmx.com
      March 27, 2018 at 2:23 am

      I can’t find…
      ~/Library/Mobile Documents/com~apple~CloudDocs
      …using macOS 10.13.3 Did they place it somewhere different for High Sierra?
      My Terminal skills aren’t the best, but still…

      • Scott
        April 2, 2018 at 11:42 pm

        @mikemac520 If you do not have iCloud Drive enabled within the iCloud System Preference, I don’t believe that you will see that folder.

  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 )

Connecting to %s

%d bloggers like this: