bye-cloud

Convert the iCloud photos archive from Apple so you can move to immich.

How to get your photos from Apple

Go to https://privacy.apple.com/accounts and request a copy of all of your data. It will take a while -- a few days, and when you get it, it won't be in a very useful format. It's almost like Apple doesn't want you to control your own photos. (You can also get your iCloud Drive files and stuff while you're there.)

Now that you have your iCloud Photos

Once you have downloaded your iCloud backups, they will be in zip files with a very specific naming convention, like iCloud Photos Part 1 of 3.zip. This backup tool assumes that's the case, and if that changes, this tool won't work until it is updated. But it is open source so you can change it yourself or at least report an issue!

It's important that you copy all those zip files into a new location where we will be operating on them. I haven't extensively tested this program out, so make sure you don't run it against your only copy.

And you must copy all of your zip files. If you only copy one of three zip files, bye-cloud will notice and complain. The reason is that apple distributes photos randomly throughout these archives, and if you try to unpack only one part, the Album spreadsheets will reference photos that bye-cloud won't be able to find.

Install

Homebrew (macOS/Linux)

brew install jakekara/tap/bye-cloud

This installs bye-cloud and ffmpeg together.

pipx

pipx install bye-cloud

uv

uv tool install bye-cloud

Note: For video date repair, ffmpeg must be installed separately when using pipx or uv. bye-cloud will warn you on startup if ffmpeg is missing.

Usage

With all of your .zip files in a folder, let's say ./icloud-parts, run the command:

bye-cloud -i ./icloud-parts -o ./export

That's it! Just wait until it finishes and your photos will be organized into folders. These should work with image libraries like immich and others.

CLI Options

bye-cloud -i ./icloud-parts -o ./export [OPTIONS]

Options:
  -v, --verbose      Enable detailed logging
  -q, --quiet        Only show warnings and errors
  --dry-run          Preview operations without modifying files
  --keep-temp        Keep temporary files (for debugging)
  --check-missing    Warn about photos missing from metadata
  --force            Overwrite output directory if it exists

A detailed log file is created in {output}/logs/ for each run.

Contributing

See CONTRIBUTING.md for development setup, running tests, and project architecture.

Note: This project includes AI-written code. I've started using Claude Code extensively since version 1.0.0 to maintain this repo as part of an effort to learn more about AI coding.