Self-hosted service
boredazfcuk/docker-icloudpd avatar
boredazfcuk/docker-icloudpd

docker-icloudpd: an Alpine container for the iCloud Photos Downloader

An Alpine Linux container for the iCloud Photos Downloader command line utility

2,971 stars243 forksShellLicense varies

At a glance

What is it?
boredazfcuk/docker-icloudpd wraps the iCloud Photos Downloader in an Alpine image so several iDevices can back up into one server folder. The README points configuration at CONFIGURATION.md, and Apple's Advanced Data Protection must be off.
Who is it for?
docker-icloudpd suits people who already run Docker at home and want several iDevices feeding one photo library on their own hardware, and who are willing to turn Advanced Data Protection off for that account. It is the wrong choice if you want ADP left on, if you will not read CONFIGURATION.md, or if re-authentication through Telegram or reauth.sh is not something you can live with.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Yes. The repository last received commits 21 days ago.
What is it written in?
Mainly Shell, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • boredazfcuk/docker-icloudpd2,971 ★ · +24
Star history
Repository2026-09-242026-11-15
boredazfcuk/docker-icloudpd2.9k3k

24 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What docker-icloudpd is for

Apple gives you no supported way to pull the photo streams of several iPhones and iPads into one folder on your own machine. The README states the author's own reason for building this: "it's the only way of backing up multiple devices to a single location." That is the whole pitch. The container exists so a household with more than one iDevice gets one destination, not one export per phone.

The audience is narrow and technical. You need a machine that stays on, Docker, and a willingness to edit a configuration file rather than click through a wizard. The repository is Shell throughout, with a Dockerfile, a launcher script, a sync script, an authentication expect script, a healthcheck and a tests directory. Nothing here is aimed at someone who wants a desktop app.

One constraint sits above everything else. The README says Apple's Advanced Data Protection is not supported and "ADP must be disabled for this container to work." If you have turned ADP on for the Apple ID you intend to sync, this project is not an option until you turn it off. That is a security decision about your account, not a configuration detail.

How the container authenticates and syncs

The moving parts are visible from the file list. authenticate.exp handles the interactive Apple login, including the multi-factor prompt. init_config.sh sets up the runtime configuration. launcher.sh starts the container's work. sync-icloud.sh performs the download run. healthcheck.sh reports whether the container is still healthy. icloudpd.dockerfile builds the image, and icloudpd.dockerfile-sourcebuild is a second build path.

Credentials go into the system keyring rather than a plain file, according to the README, which is a meaningful difference from passing a password through an environment variable that ends up in your shell history or in a compose file. The README also describes HEIC to JPG conversion as a capability of the image, and says converted JPGs are included when Nextcloud upload is configured.

Re-authentication is the part the project has invested in. Apple's session cookie expires, and the README describes two ways to renew it. The first is remote: if Telegram is configured, you message the bot, it replies asking for the multi-factor authentication code, and you send that code back through Telegram. The second is local: the README says you can "simply run reauth.sh from the Docker command line" to renew the cookie. Both paths exist because the alternative, tearing down and re-initialising the container, is worse.

Telegram also carries commands in the other direction. The README states that sending a message to the Telegram chat makes the container pick it up and sync immediately, rather than waiting for the next scheduled run.

Installing it and running a first sync

The README is a placeholder by the author's own admission: the Docker Hub description hit a 25,000 character limit and the full documentation now lives in CONFIGURATION.md at the root of the repository. So the honest first step is to read that file, not the README.

There is a docker-compose directory in the repository. That is the structure the project expects you to start from, so clone the repository and work inside it rather than inventing a compose file from scratch:

bash
git clone https://github.com/boredazfcuk/docker-icloudpd.git
cd docker-icloudpd
ls docker-compose/

The listing is the point of that last command. What you see there is the compose file and any adjacent files the project ships, and CONFIGURATION.md tells you which values to set. Do not guess variable names from this article; the image's configuration keys are defined in CONFIGURATION.md and nowhere else in the repository documentation.

Once your values are in place, bring the container up from that directory and then watch its logs. The README describes a scheduled sync loop rather than a one-shot command, so the container stays running after the first download finishes:

bash
docker compose up -d
docker compose logs -f

The healthcheck script is what tells you whether the container is still doing its job, and the log output is where the authentication flow and the download progress appear. If the login needs a multi-factor code, that is where you will see it being requested, and reauth.sh is the documented way to answer it from the command line.

Where it breaks, and when not to use it

Advanced Data Protection is the hard boundary. The README states plainly that it is not supported and must be disabled. Anyone who enabled ADP for the security it provides is being asked to give that up in exchange for local backups. That trade is defensible for some households and unacceptable for others, and the project does not pretend otherwise.

Session expiry is the second failure mode, and it is inherent to how iCloud authentication works rather than a bug in this container. The project's answer is Telegram two-way messaging or reauth.sh. If you have no Telegram bot configured and you are not comfortable dropping into the container's command line, a sync that stops working will stay stopped until you notice the logs. The README does not document rollback, so there is nothing describing how to undo a sync or recover files the container deleted.

Deletion deserves attention. The README says Nextcloud integration syncs deletes as well as uploads. That means the container is not purely additive when that feature is configured, and the documentation does not describe a dry-run mode or a confirmation step. Treat delete syncing as a feature to enable only after you trust the download side.

Finally, the image is Alpine and the tooling is Shell. There is no web interface, no dashboard and no packaged desktop client. If you want to click a button and see your photos, this is the wrong project.

How it compares with the plain icloudpd CLI

The underlying tool is the iCloud Photos Downloader command line utility, and this repository is a container around it. That is the real alternative: install icloudpd directly and drive it with a cron job.

The difference in approach is where the state lives. Running the CLI yourself means you own the scheduling, the credential storage and the multi-factor dance, and you get a process that exits when it is done. This container owns all of that for you: a long-running process, a keyring for credentials, an authentication expect script, a healthcheck, and a Telegram channel that can both trigger a sync and complete a re-authentication. You trade operational control for not having to build the re-authentication plumbing yourself.

A second comparison is worth naming. The README describes built-in Nextcloud upload and delete, so if you already run Nextcloud, this container can act as the bridge between iCloud and that server. The plain CLI does not do that. If you do not run Nextcloud, that integration is dead weight in the documentation you have to read past.

Maintenance, licensing and what to check

The repository is not archived, and the last push was on 2026-09-06. The repository has no published GitHub releases, so there is no version tag list to reason about here. The repository does carry build_version.txt and change.log at the root, and change.log is the file to read before you pull a new image, since it is the project's own record of what changed between builds.

The licence is not stated in the repository documentation provided, and the README does not name one. That matters if you plan to redistribute the image or build a product on top of it. The README does list Litecoin, Ethereum and Bitcoin addresses for donations, which tells you the project is funded by its users rather than by a company, but a donation address is not a licence. Check the repository for a licence file before you make assumptions about redistribution.

Upgrade cost is mostly the re-authentication cycle. Every image change that touches the authentication path risks invalidating a working cookie, and the recovery path runs through Telegram or reauth.sh. If you are running this on a NAS, that is the workflow to rehearse before you need it.

Editorial conclusion

docker-icloudpd suits people who already run Docker at home and want several iDevices feeding one photo library on their own hardware, and who are willing to turn Advanced Data Protection off for that account. It is the wrong choice if you want ADP left on, if you will not read CONFIGURATION.md, or if re-authentication through Telegram or reauth.sh is not something you can live with. Before adopting it, confirm which tag or branch you intend to build from, since the repository carries both icloudpd.dockerfile and icloudpd.dockerfile-sourcebuild, and check change.log for what moved in the last image you pulled.

Frequently asked questions

What is iCloud Photos Downloader and how does docker-icloudpd relate to it?

The iCloud Photos Downloader is a command line utility, and docker-icloudpd is an Alpine Linux container built around it. The README describes the container as a way to sync the photo streams of all the iDevices in a house back to a server.

Should Advanced Data Protection be turned on or off for docker-icloudpd?

It must be off. The README states that Apple's Advanced Data Protection is not supported and that ADP must be disabled for this container to work.

How do I install docker-icloudpd?

The README is a placeholder and points to CONFIGURATION.md in the repository for configuration. The repository ships a docker-compose directory, which is the structure the project expects you to start from.

How do I renew the iCloud authentication cookie in docker-icloudpd?

There are two documented routes. With Telegram configured, you message the bot to re-authenticate and it asks you for the multi-factor authentication code. Locally, the README says you can run reauth.sh from the Docker command line.

Does docker-icloudpd upload to Nextcloud?

Yes, when the Nextcloud settings are configured. The README says every file downloaded is uploaded to a Nextcloud server, that the JPGs created from HEIC conversions are included, and that deletes are synced too.

Official sources

  1. boredazfcuk/docker-icloudpd on GitHub
  2. Issues
  3. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/boredazfcuk-docker-icloudpd.svg)](https://hysenlabs.com/projects/boredazfcuk-docker-icloudpd)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/boredazfcuk-docker-icloudpd.svg)](https://hysenlabs.com/projects/boredazfcuk-docker-icloudpd)

Was this useful?