kei: fast, parallel backups
for cloud-hosted photos and videos.

kei copies cloud-hosted photos and videos into folders you control. Today that includes iCloud Photos. The goal is a fast, parallel local backup you can run once, keep as a mirror, or leave unattended in Docker.

It handles the parts that make photo backups annoying: big libraries, shared libraries, albums, Live Photos, RAW files, edited versions, retries, interrupted downloads, and existing archives you don't want to download twice.

brew install rhoopr/kei/kei

docker pull ghcr.io/rhoopr/kei:latest

Pre-built binaries for macOS, Linux, and Windows are on the Releases page. For Docker Compose, source builds, FreeBSD, and NAS setup, see Install.

[download]
directory = "/photos"

kei config setup
kei sync

The setup wizard creates ~/.config/kei/config.toml, asks where photos should land, and can save your password in the OS keyring. You'll still approve 2FA on a trusted Apple device the first time.

A tiny config looks like this:

[auth]
username = "you@example.com"

[download]
directory = "~/Photos/iCloud"

After the first run:

kei status
kei sync --recent 30d
kei list albums

• Fast, parallel downloads for large cloud photo libraries.
• A local copy of your media, with no Apple Photos library required.
• Folder layouts for dates, albums, smart folders, shared libraries, and unfiled photos.
• Original photos and videos, plus Live Photos, RAW siblings, and edited versions when you ask for them.
• Resumable downloads and checksum checks before files are marked complete.
• One-shot sync, watch mode, Docker, systemd, launchd, and Windows service support.
• Maintenance commands for status checks, local diagnostics, manifest export, verification, reconcile, reset, and existing-file import.

Today kei syncs iCloud Photos. Immich, Google Takeout, Nextcloud, and Ente support are on the roadmap.

kei is built around reliable local backup: safe file writes, explainable state, service-friendly operation, and no destructive behavior unless you explicitly ask for it.

Read the product charter and roadmap for current priorities.

[auth]
username = "you@example.com"

[download]
directory = "/photos"

[watch]
interval = 86400

Run it with kei service run, Docker Compose, or kei install.

[filters]
albums = ["Family", "Trips"]
unfiled = false
media = ["photos", "videos", "live-photos"]

You can also sync recent media for one run:

kei sync --recent 100
kei sync --recent 30d

kei import-existing
kei sync

If a kei upgrade fixes a metadata decode or capture bug, re-apply the corrected metadata to media you already downloaded, without downloading it again:

kei sync --refresh-metadata

This one-shot repair re-enumerates the selected libraries from the provider and refreshes every downloaded version it encounters before current resolution, filename, or live-photo download policy is applied. Embedded and sidecar tags follow your configured metadata outputs. The repair requires a complete library sweep, cannot use album, smart-folder, media, or date/recent filters, and does not run under kei service run. It is a manual recovery step; the permanent automatic fix is tracked in #687.

Coming from icloudpd? Read Migrating from icloudpd.

• Install
• Configuration
• Docker
• Service mode
• Commands
• Credentials
• Status
• Doctor
• Manifest export
• Product charter
• Roadmap

Open an issue for bugs or sharp edges: Issues

MIT - see LICENSE

kei's iCloud support builds on reverse-engineering from icloud-photos-downloader. kei was originally published as icloudpd-rs before broadening beyond iCloud Photos.