Your iCloud Drive.
On Your Terms.

Downloading was the easy part

My first plan was short:

• log in to iCloud, including two-factor authentication;
• find a folder;
• walk through everything inside it;
• recreate the same folder structure locally.

That got files onto my computer. It also fell apart as soon as anything went wrong.

Large downloads involve a lot of things I do not control. The connection can drop. A signed URL can expire. A remote file reference can go stale. The process can crash. Retrying the whole folder from the beginning works, technically, but it is a terrible way to spend an afternoon.

I stopped thinking of the job as one big download. iFetch would handle each file separately, and each file could be downloaded in byte ranges. If one part failed, I wanted to redo that part, not everything before it.

Building around failure

The first version looked like this:

remote file → bytes → local file

The version I trusted looked more like this:

resolve → enumerate → open → range → temp file → checkpoint
        → retry or refresh → checksum → archive → replace → report

It is longer because the short version kept finding new ways to break.

Keeping the half-finished file

iFetch writes incoming bytes to a .temp file. Next to it, a small .download file records the last completed position.

At first, those files looked like cleanup work. They turned out to be the thing that made resume possible. If the connection dropped or I stopped the process, the next run could pick up from the saved position instead of going back to zero.

The final destination stays untouched during the download. Once the temporary file is complete, iFetch calculates a checksum, archives the previous local copy under .versions/, and replaces it. A broken transfer should not ruin the good copy I already have.

Retrying stale information is pointless

Some failures needed more than another attempt. iCloud download URLs can expire, and the file object returned by the library can become stale too.

When a request returns 404 or 410, iFetch can ask for a new signed URL. If the file object itself no longer works, it resolves the file again from its iCloud path. Other temporary failures wait and retry, with longer pauses after each attempt. If the server sends a Retry-After value, iFetch listens to it.

This was one of the more useful lessons from the project. A retry only helps if the input is still valid.

Threads made hidden problems visible

Downloading several files at once made iFetch faster. It also exposed a bug in the iCloud library that I would not have seen in a simple loop.

The library loads directory children lazily. While one thread was reading the directory, another could change its internal dictionary. The result was the wonderfully literal error: dictionary changed size during iteration.

The fix was to resolve the children first, freeze that list, and only then hand the work to the thread pool. Adding threads was easy. Understanding what those threads touched took longer.

What iFetch can do

The command is simple:

python ifetch/cli.py Documents/Photos ~/Backups/Photos

iFetch can walk through owned and shared iCloud Drive folders, download several files at once, resume partial files, refresh expired cloud references, keep previous local versions, and write a JSON report when it finishes.

It also supports include and exclude filters. Directories always remain traversable, even when their names do not match a filter. Otherwise, a filter such as *.pdf could reject the Documents folder before iFetch ever finds Documents/report.pdf.

The report became more important than I expected. A progress bar feels reassuring, but it does not tell me much after the terminal closes. The report tells me which files succeeded, which failed, how many bytes moved, and what checksums were produced.

I eventually added a Google Drive exporter too. That part is less central to iFetch, but it came from the same itch. I wanted moving my own files between services to feel boring and repeatable.

Where it falls short

The biggest limitation is the feature I called "differential updates." That name promises more than the current code delivers.

iFetch uses file size to decide what to do. If there is no local file, it downloads the whole remote file in ranges. If the local file is smaller, it resumes from the local size. If both files have the same size, it assumes nothing changed.

That last case is the problem. Two files can have the same size and different contents. iFetch will miss that change because it does not compare remote and local chunk hashes.

There are other unfinished parts. Version archives exist, but there is no friendly restore command. The report does not include every skipped file. Profiles only parse JSON even though the documentation mentions YAML. Plugin failures stay out of the main transfer, which is good for the download and bad for debugging the plugin.

The largest risk is outside my code: iFetch depends on pyicloud, which talks to Apple's private interfaces. Apple can change those interfaces without warning. This is useful software built on ground I do not own.

If I return to the project, I would start with real content comparison, a restore command, better reports, and proper packaging. I would also add continuous integration so the private API failures show up sooner.

What stuck with me

Before iFetch, I thought reliability mostly meant retries. Now I think retries are the least interesting part.

The parts I trust are the boring ones: the temporary file that survives a crash, the checkpoint that saves completed work, the old copy moved out of harm's way, and the report waiting at the end. None of them is impressive alone. Together, they make failure less dramatic.

I also stopped seeing temporary files as trash. Sometimes a half-finished file is hours of saved work. Deleting it because the process failed would be the tidy thing to do and the wrong thing to do.

I do not want to overstate what a file downloader meant during the first month of a pandemic. Still, very little felt under control then. Taking one frustrating job and making it understandable was satisfying.

2026 update: what Apple changed

I came back to this project six years later to see whether Apple had closed the gap.

Apple has made parts of the experience better. macOS Sequoia added Keep Downloaded, which lets users pin iCloud Drive files and folders locally. iCloud.com can download several selected files. Apple's Data & Privacy tools can also prepare an account-level copy that includes iCloud documents.

In December 2022, Apple announced Advanced Data Protection for iCloud. It adds optional end-to-end encryption for iCloud Drive and other categories. That is good for security, but it changes the export story. When Advanced Data Protection is enabled, Apple cannot include the protected iCloud Drive data in a Data & Privacy export. A copy made from a trusted device matters more in that setup.

Finder's Keep Downloaded option solves part of the problem I had in 2020. It can keep a folder available on a Mac, which is a big improvement. The files still live inside the synchronized iCloud Drive, though. Keeping them downloaded is not the same as making an independent archive.

Apple's current guidance still points users toward Finder, Files, or iCloud.com. There is still no official general-purpose iCloud Drive CLI, and CloudKit only gives developers access to their own app containers. It does not let a tool walk through an arbitrary user's whole iCloud Drive.

So the answer in 2026 is mixed. Apple has made local access easier and iCloud data more secure. For a repeatable migration or backup with checkpoints, explicit retries, version archives, and a machine-readable report, I would still want a tool like iFetch.

That surprised me a little. Six years is a long time in software, but getting all of your files out of a cloud service is still a very different job from keeping them synced inside it.