kei is a command-line tool that backs up iCloud Photos to folders you control. Use it on your computer, server or NAS for a one-time backup or regular automatic syncs.
It supports large libraries, Shared Libraries, albums, Live Photos, RAW files and edited versions. It can resume interrupted downloads and check existing files before downloading them again.
Warning
kei is pre-release software. Minor versions may contain breaking changes.
Read the update guide and changelog before updating.
- Use macOS, Linux or Windows, or run kei in Docker on a supported computer or NAS. Choose a folder kei can write to, with room for your photos, videos, accompanying files and temporary downloads. For a new backup, start in an empty folder.
- Have your Apple Account password and a trusted Apple device ready for the six-digit 2FA code. SMS-only 2FA, app-specific passwords, and accounts with registered FIDO/WebAuthn security keys are not supported.
- kei requires iCloud Photos web access and Advanced Data Protection (ADP) turned off. Turning off ADP removes end-to-end encryption for Photos and the other data categories it protects; Apple then holds the recovery keys under standard data protection. Read Apple's explanation and kei authentication requirements before deciding. If you want to keep ADP enabled, stop here: kei cannot back up that library. Web access alone does not make ADP compatible.
Already have an icloudpd archive? Start with Migrating from icloudpd, including the import preview and path checks, before pointing kei at it. For an existing kei install, read Upgrade and compatibility before opening its state.
On macOS with Homebrew:
brew install rhoopr/kei/keiFor macOS, Linux or Windows without Homebrew, download the matching file from Releases, unpack it, and put kei in a folder on your PATH so you can run it from a terminal. Check the installed version with kei --version. Instructions for building from source and using FreeBSD are in Install.
Follow First backup with Docker to set up folders that survive container replacement, save your settings, sign in and try a small backup. Run those commands on the machine running Docker. The commands below assume kei is installed directly on your computer.
For a new installation on your computer, run:
kei config setupChoose an empty destination such as ~/Photos/kei-first-backup, your main library, and Manually when needed. Leave date and recent-item limits unset for now. Check the selected albums, file types and destination folders before saving. At Want to kick off your first sync right now?, answer no so you can try a small backup first. The default answer, yes, immediately runs one sync using your saved choices.
If you choose watch mode instead, the setup wizard still runs only once. Later kei sync commands can use the repeat interval you saved.
The setup wizard saves your settings in ~/.config/kei/config.toml and offers to save your login details. If it creates an environment file, follow the printed instructions to load it before the next command. Then try a small backup:
kei sync --recent 10
kei statusApprove the sign-in prompt on your trusted Apple device and enter the six-digit code when asked.
--recent 10 considers up to ten recent photo or video items in each selected library before applying filters. The number of downloaded files can differ: album copies, Live Photo videos and additional versions can produce more files, while filters or failed downloads can leave fewer. This is only a sample of your library.
- Read the sync summary and warnings. Failed or unfinished work still needs attention, even if some files downloaded successfully.
- Open the destination in your file manager. Look for the recent photos you expected in the album and date folders, and open a photo and video if you selected both. Live Photos normally include a still image and a MOV video.
- Run
kei statusto check progress. A clean result does not mean you selected every item or version in iCloud. You can also runkei verify --checksumsto check saved files against their recorded checksums. That check cannot tell you whether the backup includes everything in iCloud or repair damaged files.
Photos are saved in the folder set by [download].directory. Settings, saved logins and kei's record of your backup normally live under ~/.config/kei. If you use a custom configuration file, kei normally keeps its state beside that file; data_dir or KEI_DATA_DIR can change this location. Keep the state as well as your photos and videos.
By default, kei downloads originals and the videos that accompany Live Photos. Select edited versions and other versions, including RAW, explicitly if you want them. See example.config.toml.
Once the small backup looks right, run kei sync without --recent to use your saved choices. Check those settings first: any saved date or recent-item limits still apply, and the setup wizard can select all available libraries, including Shared Libraries. Check albums, smart folders, photos outside albums, edited versions and RAW options before treating the result as a full backup.
As an alternative to the wizard, a minimal config is:
[auth]
username = "you@example.com"
[download]
directory = "~/Photos/iCloud"This uses your primary library, all its regular albums, and photos and videos outside those albums. Keep settings you want to reuse in the configuration file. To limit one run to the last 30 days, use kei sync --recent 30d.
For a daily unattended run, add this table to your existing config:
[watch]
interval = 86400kei service run keeps running in your terminal; kei install sets up a background service on your computer. Follow Service mode and Authentication for startup, saved login details and what to do when Apple asks you to sign in again. Docker users should finish the container guide.
If a sync fails, check that kei can write to the destination, that there is enough free space, and that you selected the library and albums you intended. Check the sign-in requirements too. The Status and Doctor guides explain how to check your setup.
For a bug or confusing result, open an issue with your kei version, what you expected and what happened. When available, run kei support-export --output kei-support.json with the same configuration and data directory. It collects details already saved by kei without another sync and uploads nothing automatically. Review the file before attaching it. You can still report a problem if you're using an older version or the export is incomplete. See Support export for details and Docker instructions.
Some repair commands change kei's saved state or replace files. Read Backup maintenance first. Don't delete state or conflicting files just to clear a warning. When preserving older files, kei normally refuses files with hardlinks, where several paths refer to the same file. The hardlink waiver allows this case, but a change through one path can affect the others. It does not prevent kei from writing to files.
- Downloads several files at once, resumes interrupted transfers, and checks downloaded data before marking a file complete.
- Saves ordinary photo and video files without needing an Apple Photos library, arranged by album and date as you choose.
- Supports Shared Libraries, Live Photos, and optional edited and other versions, including RAW.
- Runs once or on a schedule, in Docker or as a background service on Linux, macOS or Windows.
- Provides progress reports, troubleshooting tools, file lists, backup checks, repair commands and import of existing files.
Kei automatically saves photo information in its own database. Writing that information into media files or separate XMP files requires you to enable it. See Metadata output for supported formats, cases where kei won't write, and options for repairing timestamps.
- Install
- Upgrade and compatibility
- Account state migration
- Backup maintenance
- Metadata output
- Configuration
- Docker
- Service mode
- Commands
- Credentials
- Status
- Doctor
- Manifest export
- Product charter
- Roadmap
Report bugs or confusing behavior in 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.