Jugando con Docker: iCloud Photo Library

Backups automáticos de Fotos de iCloud con Docker

Si llevas años usando iCloud Fotos, seguramente tienes ahí una parte importante de tu vida digital: fotos familiares, viajes, vídeos, capturas, recuerdos, documentos escaneados y mil cosas más que has ido acumulando sin darte cuenta.

iCloud funciona muy bien como sincronización entre dispositivos Apple.

Pero hay un matiz importante:

iCloud no debería ser tu único backup.

Si borras algo por error, si una cuenta se bloquea, si hay un problema de sincronización, si quieres migrar a otro sistema o si simplemente quieres cumplir una estrategia de backups 3-2-1, necesitas una copia fuera del ecosistema de Apple.

Puedes descargar fotos manualmente desde iCloud.com. También puedes usar un Mac con la fototeca completa descargada en local. Pero si tienes un servidor Linux, un NAS o un homelab, lo lógico es automatizarlo.

Ahí entra iCloud Photos Downloader, más conocido como icloudpd.

Nota sobre los ejemplos: las rutas, usuarios, nombres, configuraciones e identificadores utilizados en este artículo son ilustrativos y deben adaptarse a cada instalación. No representan sistemas de ninguna organización.

---

Qué es icloudpd

iCloud Photos Downloader es una herramienta open source de línea de comandos para descargar fotos y vídeos de iCloud a almacenamiento local.

Su objetivo es muy claro: permitirte tener una copia local de tu biblioteca de Fotos de iCloud en el destino que tú elijas.

Puede ejecutarse de varias formas:

• Como ejecutable para Windows, macOS o Linux.
• Como paquete Python.
• Como imagen Docker.
• En NAS o servidores domésticos.

Y soporta funciones muy interesantes:

• Descarga de fotos y vídeos en calidad original.
• Live Photos como imagen + vídeo separados.
• RAW y combinaciones RAW+JPEG.
• Deduplicación automática.
• Descargas incrementales.
• Actualización de metadatos EXIF.
• Modo continuo con intervalos.

Para mí, su caso de uso ideal es este:

iCloud Fotos → icloudpd → NAS / servidor / homelab → backup 3-2-1

Es decir: no sustituir iCloud, sino añadir una copia propia.

---

Antes de empezar: limitaciones importantes

Este punto es clave.

Apple ha ido endureciendo el acceso a iCloud, y herramientas como icloudpd dependen de que tu cuenta permita ciertos accesos.

Para que funcione, normalmente necesitas:

• Activar Access iCloud Data on the Web.
• Desactivar Advanced Data Protection.

En iPhone o iPad, revisa:

Ajustes → tu nombre → iCloud → Access iCloud Data on the Web

Y también:

Ajustes → tu nombre → iCloud → Advanced Data Protection

Si Advanced Data Protection está activado, icloudpd puede no funcionar o requerir ajustes adicionales. Apple protege más datos con cifrado de extremo a extremo y el acceso web a iCloud queda más limitado. La propia herramienta documenta errores tipo ACCESS_DENIED en ese escenario.

Esto tiene una consecuencia importante: si para usar icloudpd tienes que desactivar Advanced Data Protection, estás haciendo una decisión de seguridad. No lo escondas debajo de la alfombra.

Mi recomendación:

• Si para ti Advanced Data Protection es imprescindible, quizá esta herramienta no encaja.
• Si priorizas tener copia local automatizada, icloudpd puede tener sentido.
• En cualquier caso, protege muy bien el servidor donde se descargan las fotos.

No hay magia. Hay compromisos.

---

Copy, sync y move: no son lo mismo

Antes de escribir comandos, hay que entender los modos.

Copy

Es el modo más seguro para empezar.

Descarga fotos nuevas de iCloud a local, pero no borra nada local si lo has borrado en iCloud.

Este es el modo que recomiendo al principio. Primero copia, luego verifica, después haz backup. Hasta que no tengas eso claro, no tocaría modos más agresivos.

Sync

Sincroniza más agresivamente.

Con --auto-delete, si borras una foto en iCloud, también se elimina localmente.

Esto puede tener sentido si quieres un espejo exacto de iCloud, pero no lo llamaría “backup” sin matices. Si un borrado accidental se propaga, puedes perder también la copia local.

Move

Con --keep-icloud-recent-days, icloudpd puede descargar fotos y borrar de iCloud las más antiguas, manteniendo solo las recientes.

Esto es útil si quieres liberar espacio en iCloud, pero también es el modo más delicado.

No lo usaría hasta tener backups probados de la copia local.

Mi orden recomendado:

Primero copy.
Después verifica.
Luego haz backup.
Y solo si lo tienes claro, plantea sync o move.

---

Requisitos previos

• Servidor Linux, NAS o equipo de homelab.
• Docker instalado.
• Docker Compose V2 como docker compose.
• Cuenta de iCloud con Fotos activado.
• Espacio suficiente para toda la fototeca.
• Una estrategia de backup para la carpeta descargada.

Ten en cuenta que una fototeca de iCloud puede ocupar muchísimo. Antes de empezar, mira el tamaño aproximado en iCloud y asegúrate de que tu NAS o disco tiene margen.

También te recomiendo usar almacenamiento local o un NAS fiable. No montaría esto sobre un disco USB dudoso sin SMART, sin backup y sin monitorización.

---

Paso 1: crear la estructura de directorios

Vamos a crear una carpeta para datos y otra para cookies/sesión.

sudo mkdir -p /opt/icloudpd/data /opt/icloudpd/cookies
sudo chown -R $USER:$USER /opt/icloudpd
cd /opt/icloudpd

La carpeta data será donde se guardarán las fotos y vídeos.

La carpeta cookies guardará la sesión autenticada. Trátala como algo sensible.

---

Paso 2: crear el docker-compose.yml

Crea el archivo:

nano docker-compose.yml

Configuración base:

services:
  icloudpd:
    image: icloudpd/icloudpd:latest
    container_name: icloudpd
    restart: "no"
    environment:
      - TZ=Europe/Madrid
    volumes:
      - "./data:/data"
      - "./cookies:/cookies"
    stdin_open: true
    tty: true

Algunos matices:

• No uso version: '3'. En Compose moderno ya no hace falta.
• No dejo el contenedor en restart: unless-stopped para una ejecución manual. Prefiero controlar cuándo descarga.
• No pongo la contraseña de Apple en el Compose.
• No publico puertos porque icloudpd no necesita exponer un servicio web.

Esto es importante: no estamos montando una aplicación web. Estamos ejecutando una herramienta de descarga.

---

Paso 3: primera autenticación

Para entrar en el contenedor:

docker compose run --rm icloudpd sh

Dentro, lanza el comando de autenticación/descarga inicial:

icloudpd \
  --directory /data \
  --cookie-directory /cookies \
  --username [email protected] \
  --size original \
  --folder-structure "{:%Y/%Y-%m-%d}"

La herramienta te pedirá la contraseña y, si tienes autenticación de doble factor, el código correspondiente.

No recomiendo poner la contraseña con --password en el comando, porque puede quedar en historial, logs o procesos.

Si el primer intento devuelve un error tipo Bad Request (400), no entres en pánico. La documentación indica que puede ocurrir la primera vez porque Apple necesita preparar información asociada a tu biblioteca. Espera unos minutos y vuelve a intentarlo.

Las cookies de sesión quedarán en /cookies. No las publiques, no las subas a ningún repositorio y no las compartas.

---

Paso 4: primera descarga completa

Cuando la autenticación esté bien, ejecuta la descarga completa:

docker compose run --rm icloudpd icloudpd \
  --directory /data \
  --cookie-directory /cookies \
  --username [email protected] \
  --size original \
  --folder-structure "{:%Y/%Y-%m-%d}" \
  --set-exif-datetime

Este comando descarga en calidad original y organiza por año y fecha:

/data/2026/2026-06-24/foto.jpg

Explicación rápida:

• --directory /data: destino de descarga.
• --cookie-directory /cookies: sesión autenticada.
• --username: cuenta de iCloud.
• --size original: descarga calidad original.
• --folder-structure: estructura de carpetas.
• --set-exif-datetime: ajusta fechas EXIF cuando procede.

La primera descarga puede tardar mucho. Horas o incluso días si tienes muchos vídeos y una conexión normal.

No lo lances en un disco con poco espacio.

---

Paso 5: ejecuciones incrementales

Una vez hecha la descarga inicial, no necesitas revisar toda la biblioteca cada vez.

Puedes usar opciones como --until-found para acelerar ejecuciones repetidas:

docker compose run --rm icloudpd icloudpd \
  --directory /data \
  --cookie-directory /cookies \
  --username [email protected] \
  --size original \
  --folder-structure "{:%Y/%Y-%m-%d}" \
  --set-exif-datetime \
  --until-found 50

Esto hace que se detenga cuando encuentra una cantidad de archivos consecutivos ya descargados. Es útil para ejecuciones frecuentes.

También puedes limitar a fotos recientes:

docker compose run --rm icloudpd icloudpd \
  --directory /data \
  --cookie-directory /cookies \
  --username [email protected] \
  --size original \
  --recent 500

Mi enfoque:

• Primera ejecución: completa.
• Ejecuciones diarias: incrementales.
• Revisión periódica: ejecución más amplia para detectar huecos.

---

Paso 6: automatizar con cron

En lugar de dejar el contenedor siempre vivo con --watch-with-interval, prefiero una ejecución programada.

Es más simple, más fácil de supervisar y más predecible.

Crea un script:

nano /opt/icloudpd/sync.sh

Contenido:

#!/bin/bash
set -euo pipefail

cd /opt/icloudpd

docker compose run --rm icloudpd icloudpd \
  --directory /data \
  --cookie-directory /cookies \
  --username [email protected] \
  --size original \
  --folder-structure "{:%Y/%Y-%m-%d}" \
  --set-exif-datetime \
  --until-found 50

Dale permisos:

chmod +x /opt/icloudpd/sync.sh

Añade cron:

crontab -e

Ejemplo diario a las 03:30:

30 3 * * * /opt/icloudpd/sync.sh >> /opt/icloudpd/icloudpd.log 2>&1

Con esto tienes una descarga diaria y un log revisable.

Si prefieres ejecución continua, puedes usar --watch-with-interval, pero no lo pondría como opción principal para todo el mundo. Para un backup doméstico, cron suele ser suficiente.

---

Paso 7: opción continua con watch

Si quieres que icloudpd quede monitorizando cambios de forma continua, puedes usar:

docker compose run --rm icloudpd icloudpd \
  --directory /data \
  --cookie-directory /cookies \
  --username [email protected] \
  --size original \
  --folder-structure "{:%Y/%Y-%m-%d}" \
  --watch-with-interval 3600

El valor 3600 son segundos. Es decir, una comprobación cada hora.

Funciona, pero ten en cuenta:

• Si el contenedor se para, deja de vigilar.
• Si caduca la sesión, tendrás que reautenticar.
• Si hay errores, necesitas logs y alertas.
• No sustituye a una estrategia de backup de la carpeta local.

Por eso, para muchos casos, prefiero cron + logs + monitorización.

---

Opciones útiles de icloudpd

Opción	Qué hace	Cuándo usarla
--size original	Descarga calidad original	Casi siempre, si quieres backup real.
--folder-structure "{:%Y/%Y-%m-%d}"	Organiza por año y fecha	Para tener una biblioteca navegable.
--set-exif-datetime	Ajusta metadatos EXIF de fecha	Útil para ordenar correctamente.
--until-found 50	Para al encontrar archivos ya descargados	Ejecuciones incrementales.
--recent 500	Descarga solo elementos recientes	Pruebas o sincronizaciones ligeras.
--auto-delete	Borra localmente lo borrado en iCloud	Solo si quieres espejo, no backup puro.
--keep-icloud-recent-days 30	Borra de iCloud elementos antiguos tras descargarlos	Solo si ya tienes backup local probado.
--watch-with-interval 3600	Modo continuo por intervalo	Si quieres vigilancia permanente.

Para ver todas las opciones:

docker compose run --rm icloudpd icloudpd --help

---

Alternativa: boredazfcuk/docker-icloudpd

Existe una imagen alternativa muy popular: boredazfcuk/docker-icloudpd.

Está pensada para funcionar de forma más “appliance”, con configuración persistente y funciones adicionales.

Incluye características como:

• Uso de keyring para credenciales.
• Conversión HEIC a JPG.
• Notificaciones por Telegram, Discord, Pushover, Webhook, Signal y otros servicios.
• Healthcheck.
• Configuración persistente en /config.

Puede ser mejor opción si quieres algo más automático y con notificaciones integradas.

Pero tiene más configuración. Para entender la herramienta y controlar bien qué hace, yo empezaría con la imagen oficial y comandos explícitos. Cuando ya sabes qué quieres, puedes pasar a la imagen alternativa.

---

Seguridad y privacidad

Esto no es un contenedor cualquiera.

Vas a descargar fotos y vídeos privados. Además, vas a guardar cookies de sesión de iCloud.

Como mínimo:

• Protege /opt/icloudpd/cookies.
• Protege /opt/icloudpd/data.
• No guardes la contraseña de Apple en scripts ni Compose.
• No subas logs con rutas o nombres sensibles.
• No ejecutes el contenedor con más privilegios de los necesarios.
• Haz backups cifrados.
• Vigila espacio libre en disco.
• Comprueba permisos del usuario que ejecuta Docker.

Permisos básicos:

chmod 700 /opt/icloudpd
chmod 700 /opt/icloudpd/cookies
chmod 700 /opt/icloudpd/data

Si guardas las fotos en un NAS, revisa permisos SMB/NFS. No tiene sentido descargar toda tu fototeca y dejarla expuesta a cualquier usuario de la red.

---

Backups de la copia local

Esto puede sonar raro, pero es importante:

descargar iCloud a tu NAS no es el final de la estrategia de backup.

Es solo una copia más.

Si tu NAS falla, si borras la carpeta, si el disco se corrompe o si un ransomware cifra el almacenamiento local, puedes perder esa copia.

Lo correcto sería integrarlo en una estrategia 3-2-1:

• Original en iCloud.
• Copia local en NAS o servidor.
• Copia adicional en otro disco, otro NAS, otra nube o repositorio inmutable.

Y aquí sí recomiendo no usar --auto-delete al principio. Si quieres backup, no quieres que un borrado en iCloud se propague inmediatamente a tu copia local sin una retención.

Para backup puro, empieza con copy.

---

Problemas habituales

ACCESS_DENIED

Revisa:

• Access iCloud Data on the Web activado.
• Advanced Data Protection desactivado.
• Cuenta desbloqueada.
• Autenticación completada correctamente.

Bad Request 400 en primera ejecución

Puede ocurrir la primera vez. Espera unos minutos y vuelve a lanzar el comando.

Sesión caducada

Las cookies no duran para siempre. Tarde o temprano tendrás que reautenticar.

Por eso conviene revisar logs o tener alerta si el job falla varios días seguidos.

No descarga todo

Comprueba filtros, estructura de carpetas, espacio libre y logs. Si usaste --recent o --until-found en una primera ejecución, quizá no hiciste una descarga completa.

Espacio insuficiente

Los vídeos ocupan mucho. Muchísimo.

Antes de lanzar la descarga completa, comprueba capacidad disponible:

df -h /opt/icloudpd/data

---

Más información

• Repositorio oficial de icloudpd
• Documentación oficial
• Imagen Docker oficial
• Imagen alternativa boredazfcuk/docker-icloudpd

---

¿Y ahora qué?

Este artículo forma parte de la serie Jugando con Docker. Si te ha sido útil, te recomiendo el resto de artículos:

• Tecnología Docker para tu empresa — introducción a Docker.
• Vaultwarden con Docker.
• Proxy inverso con Caddy.
• Monitorización con Uptime Kuma.
• Mi homelab: el laboratorio de un CIO.

---

Resumen

icloudpd es una herramienta muy útil si quieres sacar tus fotos y vídeos de iCloud hacia un NAS, servidor Linux o homelab.

Pero hay que usarla con cabeza.

Mi configuración recomendada:

• Docker con imagen oficial icloudpd/icloudpd.
• Descarga inicial en modo copy.
• Sin guardar contraseña en comandos ni Compose.
• Cookies en carpeta protegida.
• Fotos en almacenamiento con espacio suficiente.
• Cron para ejecuciones periódicas.
• Logs revisables.
• Sin --auto-delete hasta entender bien el flujo.
• Backup 3-2-1 de la copia local.

La idea no es sustituir iCloud de golpe. La idea es dejar de depender únicamente de iCloud.

Porque tus fotos no son “archivos”. Son recuerdos.

Y los recuerdos importantes no deberían vivir en un solo sitio.

---

¿Tienes un NAS y quieres automatizar las copias de iCloud? ¿Usas icloudpd, Synology Photos, Immich, PhotoPrism o alguna otra solución? Cuéntalo en los comentarios — con fotos y backups, las experiencias reales valen muchísimo.