iCloud and cloud storage

OneDrive's cloud files, on Apple's terms

Updated 2026-08-08 · 4 min read

OneDrive on the Mac runs through Apple's File Provider system — the same machinery as iCloud Drive — so its files live in a managed location, arrive on demand, and vanish from the disk when space runs short. Managed well, it is seamless. Understood poorly, it eats a backup.

The states, by icon

In Finder's OneDrive section, each file carries one of three states: a cloud outline (online-only — a placeholder, no local bytes), a check (local now, evictable later), or a solid always-keep mark (pinned local). The default for new files syncing down is online-only.

Right-click to move between states: Always Keep on This Device pins; Free Up Space evicts. Both act recursively on folders.

Where the files actually are

File Provider mounts OneDrive under ~/Library/CloudStorage/OneDrive-…, with a convenience link in the sidebar. That location matters for two reasons: it is where terminal tools and scripts must look, and it sits inside ~/Library — with consequences for search and backup tools that treat Library as system territory.

The three practical rules

1. Pin what a backup must contain. Time Machine copies local bytes;

online-only files back up as stubs. Pin the folders whose loss would hurt, then check with du -sh that the bytes are really local.

1. Pin what travel needs. The plane discovers eviction reliably.
2. Let the archive stay online-only. That is the feature working — a

terabyte of history costing megabytes of disk.

Search behaviour

Names of online-only files remain searchable — metadata stays local. *Contents* do not: an evicted document's text exists only in the cloud, so content search finds pinned files and misses evicted ones with no error saying so. For a OneDrive-heavy workflow, that asymmetry — names always, contents sometimes — explains most of the mysterious search misses; OneDrive's own web search covers the evicted remainder.

Common questions

Why did OneDrive files disappear from my Mac's disk?

macOS or OneDrive evicted them to reclaim space — the online-only state. The files are intact in the cloud; pin folders to prevent it.

Can Time Machine restore OneDrive files?

Only ones that were local at backup time. Online-only files appear in backups as placeholders. Pin, then back up.