Importar Fotos de iCloud a Immich: Guía Paso a Paso

Objetivo del Laboratorio: En esta guía aprenderás a extraer de forma masiva tu biblioteca de fotos de iCloud (incluyendo álbumes y metadatos originales) usando icloudpd. Posteriormente, la importaremos de forma nativa a un servidor local de Immich mediante immich-go, garantizando la integridad de los datos y evitando duplicados durante la subida.

Herramientas a Utilizar

Herramienta	Propósito	Ventaja Clave
`icloudpd`	Descargar fotos y álbumes desde los servidores de Apple	Mantiene metadatos (EXIF/XMP), Live Photos y estructura jerárquica
`immich-go`	Subir el contenido descargado a tu instancia de Immich	Evita duplicados e importa álbumes automáticamente leyendo carpetas

Preparación del Entorno

Para empezar con la descarga de tus fotos desde iCloud, lo primero es preparar un entorno limpio en Python e instalar la herramienta necesaria.

# Iniciar entorno virtual
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install icloudpd

Autenticación y Sesión

Si es la primera vez que usas la herramienta o si tu sesión ha caducado, deberás realizar el proceso de autenticación (2FA).

# 2FA / inicio de sesión
icloudpd --username $USER --cookie-directory "D:\TU-PC\immich-mig\auth" --auth-only

Estrategia de Migración

El proceso que seguiremos se divide en dos fases: primero descargaremos todas las fotos con sus metadatos organizados por fecha, y luego realizaremos una descarga específica por álbumes para mantener esa estructura al importar a Immich. Una vez descargado todo, usaremos immich-go para subirlo a nuestra instancia.

1. Descarga Completa de la Fototeca

Este comando descarga todos los archivos originales manteniendo una estructura de carpetas por fecha y preservando los metadatos.

# Descarga completa con metadatos
icloudpd `
  --username $USER `
  --cookie-directory "D:\TU-PC\immich-mig\auth" `
  --directory "D:\TU-PC\immich-mig\photos" `
  --folder-structure "{:%Y/%Y-%m-%d}" `
  --size original `
  --set-exif-datetime `
  --xmp-sidecar

¿Qué hace este comando?

--folder-structure {:%Y}/{:%Y-%m-%d}: Crea una jerarquía tipo Año/Año-Mes-Día.
--size original: Asegura que descargamos la máxima calidad disponible.
--set-exif-datetime: Corrige o rellena la fecha EXIF si fuera necesario.
--xmp-sidecar: Genera archivos .xmp con metadatos adicionales.

2. Organización por Álbumes

Para poder recrear tus álbumes de iCloud en Immich, primero necesitamos listar qué álbumes existen y guardarlos en un archivo de texto.

$USER="[email protected]"
$COOKIE="D:\TU-PC\immich-mig\auth"

# Listar álbumes y guardar en un archivo
icloudpd --username $USER --cookie-directory $COOKIE --list-albums >> D:\TU-PC\immich-mig\albums.txt

3. Script de Descarga por Álbumes

Con la lista de álbumes generada, utilizaremos el siguiente script de PowerShell para descargar el contenido de cada álbum en su propia carpeta. Esto facilitará que Immich los identifique como álbumes independientes al importar.

$USER      = "[email protected]"
$COOKIE    = "D:\TU-PC\immich-mig\auth"
$OUTROOT   = "D:\TU-PC\immich-mig\albums"
$ALBUMLIST = "D:\TU-PC\immich-mig\albums.txt"

# Función para limpiar nombres de carpeta inválidos
function Sanitize-Name([string]$name) {
  $invalid = [regex]::Escape(([string] [IO.Path]::GetInvalidFileNameChars()))
  return ($name -replace "[$invalid]", "_").Trim()
}

# Crear directorio raíz si no existe
New-Item -ItemType Directory -Force -Path $OUTROOT | Out-Null

# Procesar cada álbum de la lista
Get-Content $ALBUMLIST | ForEach-Object {
  $album = $_.Trim()
  if (-not $album) { return }

  $folder = Join-Path $OUTROOT (Sanitize-Name $album)
  New-Item -ItemType Directory -Force -Path $folder | Out-Null

  Write-Host "Descargando álbum: $album"
  icloudpd `
    --username $USER `
    --cookie-directory $COOKIE `
    --album $album `
    --directory $folder `
    --folder-structure none `
    --size original `
    --set-exif-datetime `
    --xmp-sidecar
}

Finalizando la Migración: Importación a Immich

Una vez que tenemos todas nuestras fotos y álbumes descargados localmente, el último paso es subirlos a nuestra instancia de Immich. Para esto utilizaremos immich-go.

1. Generar Clave API en Immich

Antes de lanzar los comandos de subida, necesitamos identificarnos ante el servidor:

Accede a la interfaz web de Immich.
Haz clic en el icono de usuario (arriba a la derecha).
Selecciona Ajustes de la cuenta y luego Claves API.
Genera una nueva API KEY con todos los permisos y guárdala de forma segura.

2. Configurar el Entorno de Subida

Para facilitar la ejecución de los comandos, definiremos las direcciones y la clave como variables en PowerShell.

[!TIP] Es altamente recomendable usar la URL interna o directa de Immich (sin pasar por un Proxy Inverso como Nginx) para evitar problemas de tiempos de espera o límites de tamaño de archivo durante la migración masiva.

$SERVER = "TU_URL_DE_IMMICH" # Ejemplo: http://192.168.1.50:2283
$KEY    = "TU_API_KEY"

3. Ejecutar la Importación

Primero importaremos toda la fototeca (el timeline completo) y después los álbumes específicos. PAra realizar esta importación es muy recomendable ir importando por años y no hacerlo de forma masiva ya que puede saturar el servidor de Immich o incluso saturar la aplicación de importacion de immich-go. Otro punto importante el espacio en disco de la maquina de Immich no esté al límite o cerca del límite.

Importar el Timeline

Dependiendo del año que queremos importar solo tendremos que modificar la variable $YEAR del siguiente script con el año que queremos importar. —log-file=“RUTA$YEAR” para que nos guarde un log y nos indique si hubo errores.

$YEAR=2021
immich-go upload from-folder `
  --server=$SERVER --api-key=$KEY `
  --include-type=IMAGE `
  --concurrent-tasks=1 `
  --client-timeout=120m `
  --log-file="D:\TU-PC\immich-mig\logs\immich-go-$YEAR-images.log" `
  "D:\TU-PC\immich-mig\photos\$YEAR"

Importar los Álbumes

Este comando utilizará el nombre de cada subcarpeta para crear automáticamente el álbum correspondiente en Immich.

immich-go upload from-folder --folder-as-album=FOLDER --server=$SERVER --api-key=$KEY "D:\TU-PC\immich-mig\albums"

Troubleshooting y Consideraciones Técnicas

Limitaciones de la interfaz web de iCloud Extraer backups masivos directamente desde la web de Apple suele provocar cortes y no preserva correctamente la estructura de álbumes. Usar icloudpd permite aprovechar la API interna para garantizar descargas estables y reanudables.

Caducidad del token 2FA La sesión generada (cookie) tiene una vigencia limitada. Si el script se detiene lanzando un error de autenticación en mitad del proceso, basta con volver a ejecutar el comando --auth-only y relanzar la descarga. El proceso es idempotente y se reanudará donde lo dejó.

Gestión de archivos duplicados Importar primero la línea de tiempo completa y luego los directorios de álbumes no genera duplicados. Immich calcula el checksum de cada imagen; si detecta un duplicado durante el procesamiento de álbumes, simplemente crea el enlace simbólico al álbum correspondiente sin consumir almacenamiento adicional.

Con estos pasos tendremos migrado todo nuestro contenido de iCloud a nuestro servidor local de Immich, dejando de depender de servicios de terceros y recuperando el control total de nuestros recuerdos.

Y como siempre me gusta decir: Si este post te ha ayudado, compártelo con otros administradores que puedan beneficiarse. Y sígueme para más experiencias reales desde las trincheras del homelab.