Two kinds of files in iCloud Drive
Every file in iCloud Drive is in one of two states on your Mac:
- Downloaded. The full file is on your disk and in iCloud. It uses space on your Mac and opens instantly, even offline.
- In iCloud only. Your Mac keeps a placeholder: the name, size, dates and icon, but not the contents. It uses almost no space. Finder shows a small cloud icon next to it, and opening it downloads it first.
Both look the same in most lists. Both report the same size. That is the root of most confusion about iCloud and disk space.
What Optimize Mac Storage does
With Optimize Mac Storage turned on, macOS manages those two states for you. Apple’s wording is that older documents are stored in iCloud when space is needed. In practice:
- New and recently used files stay downloaded.
- When your disk runs low, macOS turns files you have not opened in a while back into placeholders, oldest first.
- While there is plenty of free space, it may keep everything downloaded. Turning the setting on does not free space by itself.
To find the setting, open System Settings, click your name at the top of the sidebar, then choose iCloud. Depending on your macOS version, Optimize Mac Storage is on that page or in the iCloud Drive (Drive) options.
If you also turned on Desktop and Documents Folders in iCloud Drive, those two folders follow the same rules. A file on your desktop can then be online only without you noticing.
With Optimize Mac Storage on, downloaded files that are safely in iCloud can count towards purgeable space: macOS can clear them on its own, so they show as available. The same idea is behind purgeable space in general.
Why storage numbers mislead
Different tools count placeholders differently.
- Finder sizes show the full size of every file, downloaded or not. A 200 GB iCloud Drive folder can use 3 GB on disk.
- Get Info on a file or folder shows the full size and, next to it, the much smaller amount on disk.
- Storage settings can treat downloaded files that are already in iCloud as space macOS can reclaim, which raises “available”.
- Disk analyzers and scripts vary. Tools that add up file sizes without checking the download state overstate cloud folders.
So when a folder looks huge, the useful question is not how big it is, but how much of it is on this Mac.
How to check what is really downloaded
In Finder
Open iCloud Drive in Finder. Files that are in iCloud only have a small cloud icon next to their name; downloaded files do not. Select a folder and choose File, then Get Info, to compare its full size with the space it uses on disk.
In Terminal
Placeholders carry a dataless flag, which ls -lO shows. du
reports real disk usage, so it counts them as zero:
~ % cd ~/Library/Mobile\ Documents/com~apple~CloudDocs ~ % ls -lO -rw-------@ 1 you staff - 48213504 Oct 12 09:14 report.pdf -rw-------@ 1 you staff compressed,dataless 2147483648 Apr 3 2025 holiday.mov ~ % du -sh . 3.1G . # count files that are in iCloud only ~ % find . -type f -flags +dataless | wc -l
The iCloud Drive folder lives at
~/Library/Mobile Documents/com~apple~CloudDocs. Files that other
apps keep in iCloud sit next to it in their own folders inside
~/Library/Mobile Documents.
These commands read only metadata. They do not download anything.
Taking control yourself
You can override Optimize Mac Storage for any file or folder in iCloud Drive. Control-click it in Finder, then choose:
- Remove Download to keep it in iCloud only. The file stays in iCloud and on your other devices, and your Mac gets the space back right away.
- Download Now to bring the full file back to this Mac.
- Keep Downloaded to make sure macOS never turns it into a placeholder. Use it for files you need offline, such as travel documents. Choose it again to undo.
Other cloud services work the same way
Google Drive, OneDrive, Dropbox and Box use the same macOS system for
online only files (Apple calls it File Provider). Their folders live
in ~/Library/CloudStorage, and Finder shows the same kind of cloud
icon. Each has its own name for the feature, such as streaming or
files on demand, and its own menu items to free up a download. Not
every setup works this way: Google Drive’s mirror mode and other
classic sync folders keep full copies in a normal folder, so there
is no download to remove. There, use the service’s selective sync.
Two things often catch people out:
- Old folders from previous accounts. After you sign out or
switch accounts, a folder full of downloaded copies can stay behind
in your home folder or in
~/Library/CloudStorage. It is no longer synced, so it is now just local data. Check what is in it before you remove it: it may hold the only copy of some files. - Tools that read every file. Anything that opens file contents, such as a backup app, a virus scanner or a duplicate finder, can trigger downloads of placeholders and fill your disk. Check whether a tool respects online only files before you point it at a cloud folder.
A quick checklist
- Look at how much of your cloud folders is downloaded, not how big they are.
- Remove downloads of large folders you rarely open.
- Mark the few things you need offline as Keep Downloaded.
- Look for disconnected cloud folders from old accounts.
- Never delete from iCloud Drive to save local space.
