Sweepfor Mac
Free Download

Free up storage

How to Find iCloud Files That Aren't Downloaded to Your Mac

Find which iCloud Drive files are stored in the cloud only and not downloaded locally. See what's offloaded, what takes space, and how to manage it.

8 min read

iCloud Drive on a Mac is full of half-truths. A folder shows 50GB of files but the local Mac storage shows only 10GB used. Or the opposite — a folder claims 5GB but your Mac is actually storing 30GB locally. The difference is whether files are downloaded or just placeholder references to cloud-stored content.

If you’re trying to manage Mac storage, knowing which iCloud files are local and which are cloud-only matters. Here’s how to find each, and what the differences mean.

How iCloud Drive optimization works

System Settings → Apple Account → iCloud → iCloud Drive has an “Optimize Mac Storage” toggle. With it on:

  • All your iCloud Drive files are visible in Finder
  • Recently used files stay downloaded locally
  • Older or larger files become “cloud-only” — visible as placeholders, downloaded on demand

With it off:

  • Every iCloud Drive file is downloaded locally
  • Total space matches what you see in iCloud
  • Nothing is on-demand

Most Macs ship with optimization on. The result is constant juggling: files you opened recently are local, older ones aren’t, and macOS decides without telling you.

The cloud-icon visual indicator

In Finder, files not downloaded locally show a small cloud icon next to their name. Files that ARE local don’t show the icon — they look normal.

You can see this most clearly in List View (Cmd+2). The cloud icon appears in the leftmost column for any file or folder that’s cloud-only.

For a quick visual scan: navigate to your iCloud Drive folder, switch to List View, look for cloud icons.

Tip: A folder with a cloud icon means at least some contents are cloud-only. The folder itself isn't "cloud-only" — folders can't be — but its contents might mostly be unsynced.

Finding cloud-only files via Smart Folder

Build a Smart Folder for unsynced iCloud content.

Open Finder. Choose File → New Smart Folder. Limit search to your iCloud Drive folder.

This is trickier than it sounds because Spotlight’s iCloud awareness varies. Try:

  1. Click + to add criterion
  2. Hold Option and click “Other…”
  3. Search for “ubiquitous” — that’s Apple’s term for iCloud-aware files
  4. Look for kMDItemIsiCloudFile or kMDItemUbiquitousItemDownloadingStatus

If you find them, they let you build searches like “files where downloading status is ‘NotDownloaded’.”

Most users find the Smart Folder approach inconsistent because Spotlight’s metadata for cloud state isn’t always indexed. Terminal works better.

The brctl command

brctl is the command-line tool for iCloud Drive (Apple’s “Bird” service that handles iCloud sync). It’s undocumented but functional.

brctl status

Shows current sync status.

brctl monitor com.apple.CloudDocs

Shows real-time activity for the iCloud Drive container. Useful for diagnosing sync issues.

brctl log --all

Dumps the activity log. Verbose but informative.

These don’t directly tell you what’s local vs. cloud, but they expose the underlying system.

Using find with extended attributes

iCloud-managed files have extended attributes you can detect:

find ~/Library/Mobile\ Documents/com~apple~CloudDocs -type f -name "*.icloud" 2>/dev/null

.icloud files are placeholder files for content that’s been offloaded. The actual file is in the cloud; this placeholder is what stays local. Each one is tiny (a few KB) but represents a potentially huge cloud file.

To see all of them with sizes (the real cloud-side sizes are reported in the placeholder):

ls -la ~/Library/Mobile\ Documents/com~apple~CloudDocs/.*.icloud 2>/dev/null

To count how many iCloud files are NOT downloaded:

find ~/Library/Mobile\ Documents -type f -name ".*.icloud" 2>/dev/null | wc -l

For a Mac with optimization on, this can easily be in the thousands.

Showing what IS downloaded

The opposite question: what files ARE taking local space in iCloud Drive?

du -sh ~/Library/Mobile\ Documents/com~apple~CloudDocs/* 2>/dev/null | sort -hr | head -20

Top 20 largest folders inside iCloud Drive, by ACTUAL local size. This excludes cloud-only content (the placeholders are tiny).

A folder showing 5GB locally has 5GB downloaded. A folder showing 50KB might be a placeholder shell — the underlying cloud content could be hundreds of GB.

Skip the manual huntSweep finds the largest, oldest, most-forgotten files in seconds. Download Sweep free →

Forcing a file to download or offload

To download a specific file:

brctl download /path/to/file

Or in Finder, right-click → Download Now.

To offload a file (mark it as cloud-only):

brctl evict /path/to/file

Or right-click → Remove Download.

Offloading frees local space without deleting from iCloud. The file remains in iCloud and can be redownloaded later.

For bulk offloading by folder:

find /path/to/folder -type f -exec brctl evict {} \; 2>/dev/null

The .icloud placeholder system

When a file gets offloaded, macOS replaces it with a tiny .icloud placeholder file. Filename pattern: .original-filename.icloud.

You usually don’t see these because Finder hides them and shows the original name with a cloud icon. But via Terminal:

ls -la ~/Library/Mobile\ Documents/com~apple~CloudDocs/Documents/

Reveals the .icloud placeholders alongside any locally-downloaded files.

The contents of a .icloud file is XML pointing to the cloud location. Tiny — usually under 5KB. So a folder showing 1,000 cloud-only files takes maybe 5MB of actual local space, regardless of what those 1,000 files contain in the cloud.

”Optimize Mac Storage” implications

The optimize toggle has subtle effects beyond just iCloud Drive.

With optimize on:

  • iCloud Drive files offload aggressively when space is tight
  • Photos library uses lower-resolution local versions, originals in iCloud
  • Older Messages can be offloaded
  • TV/movies you’ve watched can be removed

With optimize off:

  • Everything stays local
  • You need enough disk space for everything in iCloud
  • More predictable, less magic

If you have a 256GB Mac and 500GB of iCloud, you must have optimize on. If you have a 1TB Mac and 200GB of iCloud, you can turn it off.

The “Purgeable” relationship

Files that are downloaded locally but also exist in iCloud are technically “purgeable” — macOS could remove them under space pressure since they’re recoverable from iCloud.

This is why Storage settings sometimes shows surprising free space. A 50GB Photos library that’s all in iCloud can be considered partially purgeable, inflating “free” or “available” numbers.

To see purgeable space:

df -h /

Compare available vs. used. The gap between (capacity - used) and “Avail” is approximately purgeable space.

Reclaim 20+ gigs in one passSweep finds the caches, snapshots, and old downloads adding up to most of System Data. Free for macOS →

Strategies for reclaiming space via iCloud

If you have iCloud headroom, you can use it to free local space:

Move large folders to iCloud Drive. Then offload them. The files exist in iCloud, the local space comes back, and you can redownload anytime.

Enable Optimize Photos. Photos → Settings → iCloud → “Optimize Mac Storage.” Originals go to iCloud, smaller previews stay local.

Enable Optimize Mac Storage in Apple Account settings. Aggressive offloading of older Drive files.

Move Desktop and Documents to iCloud. System Settings → Apple Account → iCloud → iCloud Drive → Sync this Mac → “Desktop & Documents Folders.” Everything in those folders becomes iCloud-managed and can be offloaded.

The downside: you need internet to access offloaded files, and iCloud storage isn’t free past the basic 5GB tier.

When iCloud sync goes wrong

Sometimes files claim to be cloud-only but never download, or fail to upload. To diagnose:

brctl status

Shows current sync state. Look for “uploading,” “downloading,” or error states.

To kick iCloud Drive into reconnecting:

killall bird

The bird daemon (Apple’s iCloud Drive service) restarts automatically.

For deeper troubleshooting, look at logs:

log show --predicate 'subsystem == "com.apple.bird"' --last 1h

That dumps the last hour of iCloud Drive logging.

The iCloud Mail and Photos caveat

iCloud Drive is one piece. iCloud Photos and iCloud Mail are separate services with their own behavior.

Photos: Optimize Mac Storage works similarly — originals in iCloud, optimized versions local. Toggle in Photos → Settings → iCloud.

Mail: Different model. Mail downloads what you read. Settings affect retention but not on-demand offload like Drive.

Each service has its own storage management; they don’t share quotas or behavior.

Building it into routine

Most users don’t need to actively manage iCloud sync state. macOS handles it automatically with Optimize Mac Storage on.

The time it matters:

  • When local storage is critically tight
  • When you want to verify a backup is actually local before traveling without internet
  • When sync errors leave files in limbo
  • When you’ve turned optimize off and need to free space

For active management, periodically check du -sh ~/Library/Mobile\ Documents/* to see actual local sizes. If a folder is bigger than expected, something is staying local that you might want offloaded.

A cleaning tool can flag iCloud Drive folders alongside other large directories. Combined with manual offloading via brctl evict or right-click → Remove Download, you can free serious space without deleting anything.

The mental model that helps: iCloud Drive is your authoritative copy. Local files are convenience caches. Treating them that way makes the tradeoffs clearer — what’s worth keeping local, what’s fine to offload.

← Back to all guides