iCloud Ubiquitous Item
Also known as: icloud file download status, ubiquitous item ios, ios ubiquitous item, NSMetadataUbiquitousItemDownloadingStatusKey
A ubiquitous item is a file managed by iCloud that may live in the cloud rather than fully on the device. iOS represents it with a local placeholder and downloads the real contents on demand, which is why some files show as not yet downloaded.
- A ubiquitous item lives in an iCloud container and may exist locally as a placeholder, not full data.
- Check NSMetadataUbiquitousItemDownloadingStatusKey for notDownloaded, downloaded, or current state.
- Evicted placeholders take near-zero local space, so deleting one frees little but can remove it from iCloud.
What 'ubiquitous' means
In Apple's file APIs, a ubiquitous item is a file or directory stored in an iCloud container — iCloud Drive, or an app's cloud storage. The word reflects the idea that the item is available everywhere across the user's devices, but not necessarily downloaded on any one of them. iOS may keep only a lightweight placeholder locally and fetch the full data when something tries to read it.
Apps observe these items through NSMetadataQuery with a ubiquitous search scope, and check keys like NSMetadataUbiquitousItemDownloadingStatusKey to learn whether an item is `notDownloaded`, `downloaded`, or `current`. To pull the contents down, an app calls startDownloadingUbiquitousItemAtURL: on the file coordinator or file manager.
Why a file shows as not downloaded
When Optimize iPhone Storage is on, or when iCloud Drive needs space, iOS evicts the local copy of items that have a current cloud version and leaves the placeholder. In the Files app these appear with a small cloud-with-arrow icon; tapping one triggers a download. The file is still listed and its metadata is known, but its bytes are not on the device until requested.
This is also why a file can read as full-size in a listing yet take up little local storage: the size shown is the cloud item's size, while the on-device footprint of an evicted item is close to zero until it downloads.
Why it matters for cleanup
A storage tool has to distinguish a file that physically occupies space from a ubiquitous placeholder that does not. Deleting a placeholder frees almost nothing locally and may remove the item from iCloud across every device, so treating cloud-evicted items like local junk would be both ineffective and risky.
Understanding download status lets a cleaner report local versus cloud usage honestly and avoid suggesting that users delete files whose real cost lives in iCloud, not on the phone.