¿Cuánta RAM y disco necesita Immich?

¿Cuánta RAM necesita Immich?

Immich requiere 6 GB de RAM (memoria de acceso aleatorio) como mínimo documentado y 8 GB como recomendación, con 2 núcleos de CPU como límite inferior y 4 para una instalación cómoda. Esta cifra cubre toda la pila, porque Immich consta de cuatro contenedores y no de una sola aplicación. Consultar una biblioteca que ya se ha importado consume pocos recursos. La memoria se utiliza durante la importación, y la mayor parte la consume un contenedor que se puede desactivar.

[
  {
    "label": "Documented minimum",
    "ram_gb": 6,
    "cpu_cores": 2
  },
  {
    "label": "Documented recommended",
    "ram_gb": 8,
    "cpu_cores": 4
  }
]

Estas son las cifras publicadas en la página de requisitos de Immich en agosto de 2026. Son una recomendación de dimensionamiento, no una comprobación que el software realice durante el arranque. Immich se inicia con menos recursos. En un servidor más pequeño, lo que cambia es qué trabajos en segundo plano terminan y qué ocurre durante una importación cuando se agota la memoria.

Existe un límite estricto real. Immich versión 3 y posteriores necesita una CPU x86-64-v2 en hosts amd64, lo que incluye la mayoría de los procesadores vendidos desde aproximadamente 2012. En hardware antiguo, el contenedor no se inicia en lugar de ejecutarse más lentamente.

Si todavía no ha empezado la instalación, comience por la instalación completa de Immich en un VPS con Docker Compose y vuelva aquí para dimensionar el servidor.

Dónde se utiliza la memoria: cuatro contenedores

El archivo oficial de Compose inicia cuatro servicios. Cada uno tiene un perfil de memoria distinto, por lo que una sola cifra total oculta la información útil.

immich-server sirve la interfaz web y la API, y también ejecuta los workers de tareas en segundo plano. Dos workers se ejecutan dentro de ese único contenedor. api responde a las peticiones del navegador y de la aplicación móvil. microservices ejecuta las colas, incluida la generación de miniaturas y la codificación de vídeo. Las variables IMMICH_WORKERS_INCLUDE y IMMICH_WORKERS_EXCLUDE separan esos dos componentes en contenedores distintos. Así puede asignar su propio límite de memoria a la parte que genera más carga sin limitar la parte que sirve sus fotos.

database es una imagen de PostgreSQL 14 con la extensión VectorChord integrada. Almacena todos los metadatos y un vector de búsqueda por activo. La documentación de Immich establece el único mínimo explícito de la pila para este servicio: si aplica límites de recursos de Docker, la base de datos necesita al menos 2 GB. La misma página indica que la base de datos debe estar en almacenamiento SSD local y nunca en un recurso compartido de red de ningún tipo, porque las búsquedas de vectores e índices son lecturas aleatorias pequeñas y un volumen de red convierte cada una en un viaje de ida y vuelta. Si una decisión del plan depende de esto, la diferencia entre almacenamiento NVMe y SSD SATA en un VPS es más importante aquí que en cualquier otro componente de esta pila.

redis ejecuta la imagen de Valkey y almacena las colas de tareas. Es el más pequeño de los cuatro con mucha diferencia, porque almacena registros de tareas en lugar de datos de fotos.

immich-machine-learning es el servicio que determina el tamaño de su plan. Carga modelos para la búsqueda inteligente, la detección de rostros y el reconocimiento de texto, y un modelo cargado permanece residente en la memoria. MACHINE_LEARNING_MODEL_TTL tiene el valor predeterminado 300, por lo que un modelo se descarga después de cinco minutos sin peticiones y se vuelve a leer desde el volumen /cache cuando llega la siguiente. Durante una importación masiva nunca hay un intervalo de cinco minutos, por lo que los modelos permanecen cargados desde el primer activo hasta el último.

Qué cambia durante una importación

Un Immich inactivo apenas genera actividad. Las importaciones son el momento en que los servidores pequeños pueden fallar, porque cargar un recurso pone en cola una cadena de tareas y varias colas se ejecutan al mismo tiempo.

La extracción de metadatos lee la cabecera del archivo y requiere pocos recursos. La generación de miniaturas es más exigente. Immich genera tres resultados de miniatura por recurso: un marcador de posición thumbhash desenfocado, una vista previa WebP y una miniatura JPEG. También genera otra miniatura por cada rostro detectado. Cada una de esas tareas decodifica una imagen, y la concurrencia de las tareas determina cuántas imágenes se decodifican a la vez. La concurrencia es el multiplicador que convierte un coste pequeño por tarea en un coste para todo el servidor. Por eso las preguntas frecuentes de Immich la señalan como el primer valor que se debe reducir en una máquina con recursos limitados. Establezca en 1 la concurrencia de las colas pesadas en Administration, Settings, Job Settings.

Los recursos de vídeo añaden transcodificación. Cada tarea de transcodificación es un proceso independiente de FFmpeg con su propia memoria. Utilizará todos los hilos de CPU que permita.

Smart search envía cada recurso nuevo al contenedor de machine learning para calcular un vector de embedding. La detección de rostros ejecuta un segundo modelo sobre la misma imagen. Durante la primera importación de una biblioteca de fotos existente, ambas colas procesan todos los recursos disponibles durante horas. Ese es el momento de mayor consumo de memoria de toda la instalación, y ocurre una sola vez.

Por qué el reconocimiento facial y de objetos necesitan más RAM

El procesamiento facial consta de dos tareas. La detección facial ejecuta un modelo en el contenedor de machine learning y localiza los cuadros. Después, el reconocimiento facial agrupa esas detecciones por persona y consulta el índice vectorial de Postgres. Por tanto, una biblioteca grande afecta a ambos servicios en distintos momentos: primero al contenedor del modelo durante la detección y después a la base de datos durante la agrupación.

Cuatro opciones cambian lo que mantiene el contenedor de machine learning.

• El modelo facial. Immich incluye buffalo_l de forma predeterminada, y las preguntas frecuentes recomiendan buffalo_s en un servidor pequeño. Es un modelo más pequeño, por lo que consume menos memoria y se ejecuta más rápido, a cambio de una menor precisión con rostros pequeños o de perfil.
• El número de workers. MACHINE_LEARNING_WORKERS tiene el valor predeterminado 1. Cada worker es un proceso independiente que carga su propia copia de los modelos, por lo que aumentarlo a 2 aproximadamente duplica la memoria residente de los modelos. Manténgalo en 1 salvo que disponga de RAM suficiente.
• El tamaño del lote. MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION limita cuántos rostros se procesan a la vez. Un lote se mantiene completo en memoria, por lo que una foto de grupo con cuarenta rostros consume más que un retrato.
• Los tipos de modelos que se ejecutan. La búsqueda inteligente, la detección facial y el reconocimiento de texto cargan sus propios modelos. Desactive los que no utilice en Administration, Settings, Machine Learning Settings. Así libera esa memoria de forma permanente, no sólo entre importaciones.

También existe MACHINE_LEARNING_MODEL_ARENA, que está documentado como una opción que preasigna memoria de CPU para evitar la fragmentación y que está activada de forma predeterminada. Cámbiela en último lugar. Su efecto depende del asignador de memoria subyacente, por lo que la única forma fiable de evaluarlo es observar docker stats antes y después.

Tres perfiles prácticos: 2 GB, 4 GB y 8 GB

[
  {
    "label": "2 GB VPS",
    "server_limit_mb": 768,
    "db_limit_mb": 768,
    "ml_limit_mb": 0,
    "redis_limit_mb": 128,
    "notes": "machine learning container removed"
  },
  {
    "label": "4 GB VPS",
    "server_limit_mb": 1024,
    "db_limit_mb": 1280,
    "ml_limit_mb": 1024,
    "redis_limit_mb": 192,
    "notes": "machine learning on, job concurrency 1, buffalo_s"
  },
  {
    "label": "8 GB VPS",
    "server_limit_mb": 2048,
    "db_limit_mb": 2048,
    "ml_limit_mb": 2560,
    "redis_limit_mb": 256,
    "notes": "everything on at default settings"
  }
]

Interprételos como límites que debe introducir en Compose, no como mediciones del consumo de Immich. Un límite es un techo. No reserva memoria ni hace más pequeño un servicio. Determina qué servicio termina el kernel cuando el servidor se queda sin recursos. Es mejor que esa decisión la tome usted y no la propia puntuación del kernel.

El servidor de 2 GB: elimine el contenedor de machine learning

2 GB está por debajo del mínimo documentado de 6 GB. Por tanto, es un compromiso y conviene indicarlo como tal. Comente todo el servicio immich-machine-learning en docker-compose.yml, o déjelo en ejecución y desactive todos los modelos en Administration, Settings, Machine Learning Settings. Eliminar el contenedor es la opción más eficaz, porque un modelo desactivado todavía mantiene un proceso de Python residente.

Conservará las cargas, los álbumes, el uso compartido, las copias de seguridad móviles, las miniaturas y las búsquedas por fecha, ubicación y nombre de archivo. Perderá las búsquedas por descripción, la agrupación automática de caras en personas y el reconocimiento de texto dentro de las imágenes.

Los cuatro límites suman aproximadamente 1.7 GB, lo que deja al host unos 300 MB. Tenga en cuenta que 768 MB para la base de datos está por debajo del mínimo documentado de 2 GB. Ese es exactamente el compromiso que impone 2 GB. Por eso, Postgres es el servicio con más probabilidades de que el kernel termine en este caso.

Lo primero que falla es la importación, no la navegación. Una biblioteca de unas decenas de miles de fotos se navega de forma aceptable una vez importada, porque servir una página requiere una consulta de metadatos y una lectura de archivo. Una importación con muchos vídeos provocará swapping en el mismo servidor, porque la transcodificación y la cola de miniaturas necesitan memoria al mismo tiempo. Establezca la concurrencia de todas las colas pesadas en 1 y añada un archivo de swap.

El servidor de 4 GB: machine learning activado, un trabajo cada vez

4 GB es el tamaño mínimo en el que merece la pena activar el reconocimiento de caras y objetos. Limite el contenedor de machine learning a 0 MB, cambie el reconocimiento facial a buffalo_s y establezca la concurrencia de trabajos en 1 para la generación de miniaturas, la detección de caras y la búsqueda inteligente.

La primera pasada sobre una biblioteca existente tardará muchas horas y, en una biblioteca grande, más de un día. El límite principal en este caso es la CPU, no la memoria. Por tanto, añadir más RAM no acortará el proceso.

Lo primero que falla aquí es el contenedor de machine learning durante esa primera pasada masiva. Sin un límite, crece mientras un trabajo de transcodificación también consume más memoria, y el kernel termina el proceso que considera más grande. Verá Exited (137) en docker ps -a y un contenedor reiniciado, mientras la cola queda silenciosamente más atrasada que antes.

El servidor de 8 GB: la recomendación documentada

8 GB con 4 núcleos coincide con la recomendación de Immich. Todo se ejecuta con la configuración predeterminada: búsqueda inteligente, detección de caras, reconocimiento de texto y transcodificación, con la concurrencia predeterminada. Las bibliotecas de más de cien mil recursos funcionan con comodidad en este tamaño. La presión pasa de la memoria a la velocidad del disco, porque la base de datos trabaja todo el día con el índice vectorial y las consultas de metadatos.

Establezca los límites de todos modos. En un servidor con margen, los límites impiden que una cola fuera de control arrastre consigo la base de datos. Si compara el coste con las opciones más pequeñas, lo que cuesta realmente un VPS según el nivel de memoria suele hacer que el plan de 8 GB sea la forma más económica de evitar ajustes constantes.

Cómo limitar la memoria por servicio con límites de Compose

No edite docker-compose.yml para esto. Ese archivo se reemplaza cada vez que actualiza con wget. Coloque los límites en docker-compose.override.yml, junto a él. docker compose los combina automáticamente.

services:
  immich-server:
    deploy:
      resources:
        limits:
          memory: 1024M
  immich-machine-learning:
    deploy:
      resources:
        limits:
          memory: 1024M
          cpus: '1.5'
  database:
    deploy:
      resources:
        limits:
          memory: 1280M
  redis:
    deploy:
      resources:
        limits:
          memory: 192M

docker compose up -d
docker stats --no-stream

docker stats debería mostrar ahora el límite configurado en la columna MEM USAGE / LIMIT, en lugar de la memoria total del host. Si la columna del límite sigue mostrando el tamaño completo del host, no se cargó el archivo de sobrescritura. Compruebe el nombre del archivo y ejecute docker compose config para ver el resultado combinado.

Un límite demasiado bajo convierte un servicio lento en un servicio detenido. Auméntelo si un contenedor empieza a reiniciarse continuamente. Encontrará más información sobre el funcionamiento en configurar límites de memoria por servicio en Docker Compose, incluido el motivo por el que deploy funciona fuera de Swarm con Compose v2.

Cómo desactivar o mover el contenedor de machine learning

En un servidor pequeño, mover este contenedor a otro equipo es el cambio más importante que puede hacer. Immich permite ejecutarlo en otra máquina. Cree este archivo en el segundo host. Puede ser un equipo de escritorio que sólo esté encendido por las noches:

name: immich_remote_ml
services:
  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    volumes:
      - model-cache:/cache
    restart: always
    ports:
      - 3003:3003
volumes:
  model-cache:

docker compose up -d
curl -s http://localhost:3003/ping

A continuación, vaya a Administration, Settings, Machine Learning Settings en la interfaz web, haga clic en Add URL e introduzca http://<host>:3003. Mantenga la misma versión en ambos hosts. La documentación de Immich advierte que las diferencias de versión entre ambos provocan errores e inestabilidad.

Ese puerto transmite sus fotos al otro equipo sin cifrado. Manténgalo en una red privada o utilícelo mediante un túnel WireGuard entre ambos hosts. No exponga nunca el puerto 3003 a Internet.

Si el problema es tener un contenedor de modelos ejecutándose de forma permanente, también es razonable comparar las diferencias entre PhotoPrism e Immich respecto a lo que ejecutan de forma permanente antes de elegir un tamaño de plan.

¿Cuánto espacio de disco necesita una biblioteca de Immich?

No existe un multiplicador único, porque cuatro elementos distintos crecen a ritmos diferentes. Este es el cálculo para una biblioteca con 50,000 fotos y 500 videos cortos.

[
  {
    "label": "Originals: 50,000 photos at 4 MB",
    "gb": 200
  },
  {
    "label": "Originals: 500 videos at 120 MB",
    "gb": 60
  },
  {
    "label": "Thumbnails and encoded video at 15%",
    "gb": 39
  },
  {
    "label": "Postgres database",
    "gb": 3
  },
  {
    "label": "Machine learning model cache",
    "gb": 2
  }
]

Los 200 GB de fotos y 60 GB de video son supuestos. Sustitúyalos por sus propios promedios antes de comprar hardware, porque el video determina esta cifra: un minuto de video de un teléfono ocupa más espacio que cien fotos.

find /srv/immich/upload -type f -printf '%s\n' \
  | awk '{n++; s+=$1} END {printf "%d files, %.1f MB average\n", n, s/n/1048576}'

La fila de 39 GB es la única proporción publicada por Immich: las miniaturas generadas y el video transcodificado añaden entre 10 y 20 por ciento al tamaño de la biblioteca, como promedio. Es un intervalo porque depende de cuántos recursos sean videos que necesiten volver a codificarse para que sean compatibles con el navegador. Una biblioteca de archivos JPEG se sitúa cerca del extremo inferior de ese intervalo.

La base de datos ocupa 3 GB, y ese valor es casi fijo. Immich documenta que los archivos de la base de datos suelen ocupar entre 1 y 3 GB, porque contienen metadatos y vectores de búsqueda, no píxeles. La caché de modelos ocupa 2 GB y crece si habilita varios modelos o prueba modelos diferentes. Las preguntas frecuentes señalan este volumen como consumidor de espacio precisamente por ese motivo.

Las cinco filas suman algo más de 300 GB, por lo que un volumen de 500 GB deja espacio para crecer y uno de 250 GB no. Supervise la distribución con:

grep UPLOAD_LOCATION .env
du -sh /srv/immich/*

Hay seis carpetas bajo UPLOAD_LOCATION. upload y library contienen los originales, thumbs contiene las vistas previas y las miniaturas de rostros, encoded-video contiene las copias recodificadas, profile contiene los avatares y backups contiene los volcados automáticos de la base de datos. Sólo upload, library y profile son irremplazables, porque todo lo demás se puede regenerar a partir de ellos.

Hay dos aspectos que suelen sorprender. Los recursos eliminados pasan primero a la papelera y conservan su espacio hasta que se vacía. Por tanto, una limpieza grande no libera espacio el mismo día en que se realiza. Además, un volcado de la base de datos sólo contiene metadatos, por lo que no sirve sin los archivos:

docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > /srv/backups/immich-dump.sql.gz

Combine esto con una copia a nivel de archivo de los originales en una ubicación fuera del servidor. Para eso sirven las copias de seguridad de restic desde un VPS a almacenamiento externo.

La transcodificación usa CPU, no RAM

Añadir RAM no hará que la transcodificación sea más rápida. Immich transcodifica con FFmpeg y, en un VPS sin aceleración, la CPU decodifica y codifica cada fotograma. Incluso cuando hay aceleración por hardware, Immich documenta que sólo se acelera la codificación. La CPU sigue realizando la decodificación por software y el mapeo de tonos.

La aceleración por hardware requiere el archivo adicional de Compose hwaccel.transcoding.yml y un dispositivo que se pase al contenedor mediante NVENC, Quick Sync, RKMPP o VAAPI. La mayoría de los planes VPS no proporcionan ninguno de estos recursos. Por tanto, planifique el uso de CPU.

El ajuste práctico es el número de subprocesos. En Administration, Settings, Video Transcoding Settings, un valor de 0 usa todos los núcleos. Esto puede bloquear la interfaz web si un vídeo se transcodifica en un plan de 2 núcleos. Establezca allí el valor en 1 o 2, como recomienda la sección FAQ de Immich. La transcodificación será más lenta, pero no interrumpirá el servicio.

Por qué una importación con intercambio excesivo parece bloqueada

Este es el fallo que más se interpreta mal. Cuando Immich se queda sin memoria, se producen dos resultados y sólo uno parece un fallo.

Sin swap, el kernel mata un proceso. El contenedor se reinicia en cuestión de segundos, por lo que, desde el navegador, la cola de trabajos simplemente se detiene y después continúa. La evidencia está en docker ps -a:

docker ps -a --filter name=immich
docker inspect immich_machine_learning | grep -i oomkilled
sudo dmesg -T | grep -i -E 'out of memory|oom-kill'

Exited (137) indica que el proceso terminó con la señal 9. 137 es 128 más 9. Un valor OOMKilled de true confirma que terminó por falta de memoria y no debido a un fallo del proceso.

Con swap, no se mata ningún proceso ni se produce ningún error. El kernel empieza a mover páginas al disco, la importación se ralentiza en un orden de magnitud y la interfaz web deja de responder dentro del tiempo de espera normal. Todos los contenedores siguen en ejecución. Todas las comprobaciones de estado pueden seguir pasando. Parece un bloqueo y, en este punto, algunas personas reinician el equipo, lo que pierde el progreso de la cola y no cambia nada.

free -m
vmstat 1 5

Los valores distintos de cero sostenidos en las columnas si y so de vmstat indican que la máquina lee y escribe swap continuamente. Esto es la definición de thrashing. La fila free -m correspondiente a Swap usado también aumentará al mismo tiempo.

Añada swap de todos modos en un equipo de 2 GB o 4 GB, porque una importación lenta que se puede diagnosticar es preferible a un contenedor terminado que no se puede diagnosticar:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Después, corrija la causa. Reduzca la concurrencia de trabajos a 1, limite el contenedor de machine learning o muévalo a otro host. Swap le da tiempo para hacerlo. Por sí solo, no es la solución.

FAQ

¿Puedo ejecutar Immich en un VPS de 2 GB?

Sí, con el servicio immich-machine-learning comentado en docker-compose.yml y la concurrencia de trabajos establecida en 1. Esto está por debajo del mínimo documentado de 6 GB, así que debe considerarlo una concesión conocida. Mantendrá las cargas, los álbumes, el uso compartido, las copias de seguridad del móvil y las búsquedas por fecha, ubicación y nombre de archivo. Perderá las búsquedas por descripción, la agrupación automática de rostros en personas y el reconocimiento de texto dentro de las imágenes. Añada un archivo de swap de 2 GB para que un pico durante la importación ralentice el servidor en lugar de provocar la terminación de un contenedor.

¿Por qué se detiene mi importación de Immich sin mostrar ningún mensaje de error?

Dos causas distintas pueden parecer idénticas desde el navegador. Puede que un contenedor haya sido terminado por falta de memoria; en ese caso, docker ps -a muestra Exited (137) y el contenedor ya se ha reiniciado. También puede que el host esté usando swap; en ese caso, todos los contenedores siguen ejecutándose y todo funciona simplemente muy despacio. vmstat 1 5 permite distinguir ambos casos: los valores distintos de cero sostenidos en las columnas si y so indican que se está usando swap. Reduzca la concurrencia de trabajos para la generación de miniaturas, la detección de rostros y la búsqueda inteligente en cualquiera de los dos casos.

¿Qué significa el código de salida 137 en los registros de Immich?

137 es 128 más la señal 9, por lo que el proceso terminó con SIGKILL. En la práctica, esto significa que se alcanzó un límite de memoria, ya sea el límite propio del contenedor o la falta de memoria del host. Compruébelo con docker inspect immich_machine_learning | grep -i oomkilled. Un valor de true confirma que el kernel lo terminó por falta de memoria, y free -m más sudo dmesg -T | grep -i oom-kill indican si se alcanzó el límite del contenedor o si se quedó sin memoria todo el host. El contenedor de machine learning suele ser el afectado porque normalmente contiene el proceso más grande.

¿Cuánto espacio de disco necesita Immich por foto?

Reserve el tamaño del archivo original más entre un 10 y un 20 por ciento. Immich documenta que las miniaturas generadas y los vídeos transcodificados aumentan el tamaño de la biblioteca entre un 10 y un 20 por ciento de media, y que la base de datos suele ocupar entre 1 y 3 GB incluso con una biblioteca grande. El vídeo es lo que realmente determina el total, así que mida el tamaño medio de sus propios archivos antes de elegir un plan, en lugar de aplicar un multiplicador al número de fotos.

¿Necesito una GPU para Immich?

No. Todas las partes de Immich se ejecutan en la CPU. Una tarjeta gráfica acelera la inferencia de modelos en el contenedor de machine learning y la codificación de vídeo, pero ninguna de las dos es necesaria. La mayoría de los planes VPS no ofrecen una. En hardware que sólo use CPU, establezca los hilos de transcodificación en 1 o 2, use el modelo de rostros buffalo_s y deje que la primera importación masiva se ejecute durante la noche.