semvec/pypi-packages huggingface dataset:
bye-cloud 1.0.2
Convert iCloud Photos backup to a useful folder structure
Requires Python: >=3.13

# 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](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)

```bash
brew install jakekara/tap/bye-cloud
```

This installs bye-cloud and ffmpeg together.

### pipx

```bash
pipx install bye-cloud
```

### uv

```bash
uv tool install bye-cloud
```

**Note:** For video date repair, [ffmpeg](https://ffmpeg.org/) 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](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.