Tienes veinte años de fotos en el móvil y una cuota mensual por guardarlas en un sitio que no controlas. Immich es el gestor de fotos y vídeo autoalojado que ha convertido esa cuota en un contenedor más de tu servidor: sube el carrete solo, reconoce caras y busca por lo que se ve en la imagen. Aquí está la instalación real, comprobada contra la v3.1.0, con el fichero de compose oficial, el contenedor de aprendizaje automático y la copia de seguridad que casi nadie hace bien.

Puntos clave

  • Immich dejó de ser un experimento en octubre de 2025: la v2.0.0 fue su primera versión estable y el viejo aviso de "esperad fallos y pérdidas" desapareció del README.
  • Instalar Immich son dos ficheros descargados de la última publicación, docker-compose.yml y .env, y un docker compose up -d. El servidor escucha en el puerto 2283.
  • El contenedor de aprendizaje automático es opcional, pero es el que da caras, etiquetas y búsqueda por texto libre. Con 4 GB de RAM hay que desactivarlo.
  • La base de datos guarda las rutas de cada fichero y no se reconstruye escaneando la carpeta. Copiar solo las fotos deja una biblioteca que Immich no sabe leer.
  • Fijar IMMICH_VERSION importa: bajar de versión no está admitido, ni siquiera dentro de la misma versión menor.

Qué es Immich y si sigue siendo un proyecto inestable

Immich es un gestor de fotos y vídeo que instalas en tu propia máquina, con licencia AGPL-3.0 y 112.964 estrellas en su repositorio de GitHub[1] a finales de agosto de 2026. El proyecto nació en febrero de 2022 y durante casi cuatro años su README llevó un apartado de advertencias que decía, entre otras cosas, "Do not use the app as the only way to store your photos and videos". Ese apartado seguía ahí en la v1.135.0.

Ese aviso ya no está, y merece la pena decirlo alto porque medio internet sigue copiándolo. Las notas de la versión v2.0.0[2], publicada el 1 de octubre de 2025, lo dejaron por escrito: "This release marks the first stable version of Immich". Lo único que queda hoy en el README es una advertencia distinta y bastante más sensata, la de seguir siempre una estrategia de copias 3-2-1 con tus fotos.

La versión con la que he probado todo lo que viene a continuación es la v3.1.0, publicada el 29 de julio de 2026. La rama v3 llegó el 2 de julio de 2026 y trajo cambios incompatibles, aunque la mayoría afectan a la API y por tanto a herramientas de terceros: para quien solo usa la web y el móvil, actualizar siguió siendo lo de siempre.

Qué hace falta antes de empezar

Los requisitos oficiales son concretos y conviene mirarlos antes de comprar hierro:

  • Sistema operativo Linux o similar de 64 bits. Windows y macOS funcionan peor con Docker y la documentación los desaconseja.
  • 6 GB de RAM como mínimo y 8 GB recomendados. Con 4 GB se puede ejecutar Immich desactivando el aprendizaje automático.
  • Dos núcleos como mínimo, cuatro recomendados. Hay imágenes para amd64 y arm64.
  • Desde la v3, en amd64 hace falta un procesador con nivel x86-64-v2, es decir, aproximadamente de 2012 en adelante.
  • Un sistema de ficheros con permisos de usuario y grupo de verdad, como EXT4, ZFS o APFS. La base de datos no puede vivir en un recurso de red, ni en NTFS ni en FAT.

Un detalle de dimensionado que sorprende a mucha gente: las miniaturas y los vídeos transcodificados añaden entre un 10 y un 20 % al tamaño de la biblioteca original. Si subes 500 GB de carrete, reserva 600.

Instalación con el fichero de compose oficial

La documentación insiste en un punto que se salta todo el mundo: hay que usar el docker-compose.yml de la publicación actual, no el de la rama principal, porque el de main puede no ser compatible con la última versión publicada. Los pasos oficiales son estos:

  1. Crea el directorio del proyecto con mkdir ./immich-app y entra en él.
  2. Descarga el docker-compose.yml y el example.env de la última publicación.
  3. Renombra el segundo a .env y edita UPLOAD_LOCATION, DB_PASSWORD y, si quieres, TZ.
  4. Levanta la pila con docker compose up -d.
  5. Abre http://<ip-del-servidor>:2283 y crea la cuenta de administración.

En comandos, y sin adornos:

mkdir ./immich-app && cd ./immich-app

wget -O docker-compose.yml 
  https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

wget -O .env 
  https://github.com/immich-app/immich/releases/latest/download/example.env

## edita .env antes de arrancar
docker compose up -d

El fichero que se descarga declara cuatro servicios. Este es el esqueleto real, recortado a lo que importa:

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on:
      - redis
      - database
    restart: always

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9@sha256:8e8d64b405ce18f41b8e5ee20aa4687a8ed0022d1298f2ce31cdcf3a76e09411

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    shm_size: 128mb

volumes:
  model-cache:

Hay dos decisiones de diseño ahí dentro que explican por qué actualizar Immich es tan poco dramático. La primera: Redis no es Redis, es Valkey 9, y tanto esa imagen como la de PostgreSQL vienen fijadas por digest, no por etiqueta móvil. Un docker compose pull actualiza el servidor y el modelo, pero no te cambia el motor de base de datos por sorpresa. La segunda: solo hay un volumen nombrado, model-cache. Todo lo demás son montajes contra rutas tuyas que tú decides, cosa que agradecerás el día que muevas la máquina. Si no tienes claro cuándo conviene un volumen y cuándo un montaje, lo tratamos en detalle en volúmenes y bind mounts en Docker.

Qué hay realmente dentro del fichero .env

El example.env oficial es corto y no tiene ni una variable de relleno:

# dónde se guardan tus ficheros subidos
UPLOAD_LOCATION=./library

## dónde vive la base de datos (los recursos de red no valen)
DB_DATA_LOCATION=./postgres

## TZ=Etc/UTC

## la versión de Immich; puedes fijarla a algo como "v3.1.0"
IMMICH_VERSION=v3

## secreto de conexión de postgres: cámbialo por una cadena aleatoria
## usa solo caracteres A-Za-z0-9, sin espacios ni símbolos
DB_PASSWORD=postgres

DB_USERNAME=postgres
DB_DATABASE_NAME=immich

La restricción de caracteres en DB_PASSWORD no es un capricho: la cadena viaja por una URL de conexión y los símbolos rompen el análisis. Y el valor IMMICH_VERSION=v3 es una etiqueta de versión mayor, así que te mantiene dentro de la rama 3 sin saltar sola a la 4. Si prefieres que ese secreto no acabe en texto plano dentro del directorio del proyecto, en variables de entorno y secretos en Docker hay alternativas que encajan aquí sin tocar el compose oficial.

El contenedor de aprendizaje automático y sus opciones de hardware

immich-machine-learning es el que hace tres cosas que la gente da por sentadas: detecta y agrupa caras, etiqueta el contenido de las imágenes y alimenta la búsqueda inteligente. Esa búsqueda usa modelos CLIP y la extensión VectorChord de PostgreSQL, y permite escribir "perro en la playa al atardecer" sin que ninguna de esas palabras esté en los metadatos de la foto. Hay familias de modelos multilingües (nllb, xlm, siglip2) y el español está entre los idiomas admitidos, así que no hace falta buscar en inglés.

Por defecto todo eso corre sobre la CPU, que es lento pero funciona. La documentación de aceleración por hardware[3] describe cinco alternativas: CUDA para NVIDIA, ROCm para AMD, OpenVINO para las gráficas integradas de Intel, ARM NN para las Mali y RKNN para los SoC Rockchip. Activar una es un cambio de tres líneas: descargas el hwaccel.ml.yml, añades el sufijo a la etiqueta de la imagen y descomentas el bloque extends.

immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}-cuda
    extends:
      file: hwaccel.ml.yml
      service: cuda

Las letras pequeñas importan y la documentación las dice sin adornos. CUDA exige capacidad de computo 5.2 o superior y controlador 545 o posterior. ROCm necesita 35 GiB de disco libre solo para la imagen. ARM NN acelera el etiquetado pero no la latencia de búsqueda, por incompatibilidad de modelos. Y OpenVINO sobre gráfica integrada da más problemas y consume más memoria que la propia CPU, así que no es una mejora automática.

Si tu máquina tiene 4 GB de RAM, la decisión es otra: quitar el servicio del compose y quedarte con un gestor de fotos que sincroniza, ordena por fecha y muestra el mapa. Sigue siendo útil. Simplemente no busca por contenido.

Dónde vive la biblioteca

Todo lo que sube el usuario cuelga de UPLOAD_LOCATION, con esta estructura:

Carpeta Qué guarda Se puede regenerar
upload/ los originales subidos desde web, móvil o línea de comandos no
library/ los originales cuando activas la plantilla de almacenamiento no
profile/ los avatares de cada usuario no
thumbs/ miniaturas y previsualizaciones, incluidas las de caras sí
encoded-video/ vídeos recodificados para compatibilidad sí
backups/ volcados automáticos de la base de datos sí

Las tres primeras son las que no admiten pérdida. Las otras tres se reconstruyen relanzando los trabajos de miniaturas y transcodificación, a cambio de unas cuantas horas de CPU. La base de datos, por su parte, vive aparte en DB_DATA_LOCATION, y esa separación es deliberada.

Sobre las carpetas de UPLOAD_LOCATION la documentación es tajante: no se tocan los ficheros de dentro por ningún motivo salvo para copiarlos. Renombrar o borrar algo a mano deja registros huérfanos en la base de datos y ficheros que ya nadie referencia.

La aplicación móvil y la copia del carrete

La aplicación está en Google Play y en la App Store, y también hay APK firmados en cada publicación de GitHub. La configuración es un único dato: la dirección del servidor, en el formato http://<ip-de-la-maquina>:2283. A partir de ahí, en la pantalla de la nube eliges qué álbumes del teléfono se copian y pulsas "Enable Backup".

Merece la pena distinguir dos comportamientos. La copia en primer plano arranca al abrir la aplicación y es la fiable. La copia en segundo plano depende del sistema operativo del teléfono y de sus políticas de ahorro de energía, así que en Android conviene excluir Immich de la optimización de batería si quieres que suba sin abrirla.

Un aviso concreto para quien use iCloud: si liberas espacio desde Immich, las fotos borradas del carrete quedan solo en tu servidor y desaparecen de iCloud en todos los dispositivos con esa cuenta de Apple. Es exactamente lo que pides, pero conviene entenderlo antes de pulsar.

La copia de seguridad que casi todo el mundo hace mal

Aquí es donde se pierde una biblioteca. Mucha gente copia la carpeta de fotos, ve los ficheros ahí y se queda tranquila. La documentación de copias explica por qué eso no basta: "Immich stores file paths and user metadata in the database. It does not scan the library folder, so database backups are essential". Sin la base de datos tienes un montón de ficheros con nombres opacos y ninguna forma de que Immich los reconozca.

Immich ayuda algo: genera volcados automáticos en UPLOAD_LOCATION/backups, por defecto los últimos 14, uno diario a las 2:00, ajustables desde la administración. Pero esos volcados contienen metadatos, no fotos, y viven en el mismo disco que todo lo demás. Son un seguro contra un error de migración, no contra un disco muerto.

El volcado manual, tal y como aparece en la documentación de copia y restauración[4]:

docker exec -t immich_postgres pg_dump --clean --if-exists 
  --dbname=immich --username=postgres 
  | gzip > /copias/immich/dump-$(date +%F).sql.gz

Diagrama del orden correcto de la copia de seguridad de Immich: parar immich-server, volcar la base de datos PostgreSQL, copiar upload, library y profile, y enviar la copia fuera.

Y ahora la parte que casi nunca se cuenta: el orden. Si copias base de datos y ficheros mientras Immich funciona, ambos pueden quedar desincronizados. Lo ideal es parar el contenedor immich-server durante la copia. Si eso no es viable, la documentación recomienda copiar primero la base de datos y después los ficheros. Así, en el peor caso, te quedan ficheros que la base de datos desconoce, que se pueden volver a subir a mano. Al revés acabas con una base que apunta a fotos que no están en la copia, y eso ya son activos rotos.

Para llevar el resultado fuera de la máquina, cifrado y con retención, lo natural es enganchar esto a una copia con Restic y programar el volcado justo antes.

Dos avisos más sobre la restauración: solo funciona sobre una instalación completamente nueva, en la que el servidor no haya arrancado nunca, y el procedimiento cambió en la v2.5.0, así que un volcado antiguo necesita las instrucciones de su propia versión.

Cómo se actualiza

La actualización normal son dos órdenes:

docker compose pull && docker compose up -d
docker image prune

Con tres reglas alrededor. Si has fijado IMMICH_VERSION a una versión mayor, hay que subirla a mano antes de un salto de rama, como el v2 a v3 de julio de 2026. Bajar de versión no está admitido, ni siquiera entre versiones menores, así que la copia previa no es opcional. Y el servidor solo mantiene compatibilidad con su propia versión mayor mientras que las aplicaciones móviles aguantan la actual y la anterior: por eso conviene actualizar los móviles antes que el servidor, y no al revés.

Immich frente a Nextcloud Memories y PhotoPrism

Las tres opciones resuelven el mismo problema por caminos distintos:

Immich Memories (Nextcloud) PhotoPrism
Estrellas en GitHub 112.964 3.830 40.124
Aplicación móvil propia sí usa la de Nextcloud no
Copia automática del carrete integrada vía Nextcloud vía PhotoSync o WebDAV
Búsqueda por contenido CLIP con VectorChord limitada etiquetado propio
Licencia AGPL-3.0 AGPL-3.0 mixta

La diferencia decisiva para el caso de uso "quiero dejar Google Fotos" es la primera columna de la tabla. La documentación de PhotoPrism[5] reconoce que no tiene aplicación propia y recomienda PhotoSync o cualquier cliente WebDAV. Funciona, pero es una pieza más que mantener y una experiencia peor para quien solo quiere que el móvil suba las fotos sin pensar.

Memories[6] es la elección lógica si ya tienes Nextcloud en marcha, porque hereda usuarios, compartidos y cifrado sin montar nada nuevo. Si aún no lo tienes, instalar Nextcloud entero para gestionar fotos es cargar con mucho más de lo que pides; en cómo instalar Nextcloud con Docker se ve el tamaño real de esa pila.

PhotoPrism sigue teniendo el mejor tratamiento de RAW y una interfaz muy pulida. Si tu prioridad es catalogar un archivo fotográfico y no sincronizar un teléfono, la comparación se aprieta bastante.

Preguntas frecuentes

¿Puedo usar Immich sin el contenedor de aprendizaje automático?

Sí. Quitas el servicio immich-machine-learning del compose y Immich sigue subiendo, ordenando y mostrando el mapa y las fechas. Pierdes el reconocimiento de caras, el etiquetado y la búsqueda por texto libre. Es la configuración recomendada por la propia documentación para máquinas con 4 GB de RAM.

¿Necesito un dominio y HTTPS para usar la aplicación móvil?

No para probarlo dentro de casa: la dirección http://<ip>:2283 funciona en la red local. Para subir el carrete desde la calle sí conviene un proxy inverso con certificado, porque estarás enviando tus fotos y tu contraseña por internet.

¿Immich borra las fotos del móvil cuando las sube?

No por su cuenta. Existe una función explícita de liberar espacio que borra del teléfono lo que ya está en el servidor, y hay que activarla. Si usas iCloud, ten en cuenta que ese borrado también saca las fotos de iCloud en todos tus dispositivos.

Conclusión

Instalar Immich es descargar dos ficheros, cambiar tres valores y levantar cuatro contenedores. La parte que de verdad decide si esto sale bien no es la instalación: es entender que la base de datos guarda las rutas y que una copia sin ella no sirve de nada, y decidir con honestidad si tu máquina tiene RAM para el contenedor de aprendizaje automático o si prefieres un gestor de fotos sin caras ni búsqueda semántica. El aviso de proyecto inestable ya no aplica desde la v2.0.0, pero la regla 3-2-1 sí, y con veinte años de fotos en juego esa es la única parte innegociable. La versión en inglés de este artículo está en How to install Immich with Docker.

Fuentes

  1. su repositorio de GitHub
  2. versión v2.0.0
  3. documentación de aceleración por hardware
  4. documentación de copia y restauración
  5. documentación de PhotoPrism
  6. Memories
  7. Immich, instalación con Docker Compose
  8. Immich, requisitos de hardware y software
  9. Immich, actualización