Quanta RAM e disco o Immich precisa?

De quanta RAM o Immich precisa?

O Immich requer 6 GB de RAM (memória de acesso aleatório) como mínimo documentado e 8 GB como recomendação, com 2 núcleos de CPU no limite inferior e 4 para uma instalação confortável. Esse valor abrange toda a stack, porque o Immich é composto por quatro containers, e não por uma única aplicação. Consultar uma biblioteca que já foi importada consome poucos recursos. A memória é consumida durante a importação, e a maior parte é usada por um container que pode ser desativado.

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

Esses são os valores publicados na página de requisitos do Immich em agosto de 2026. São recomendações de dimensionamento, não uma verificação que o software faz ao arrancar. O Immich arranca com menos memória. Num servidor menor, o que muda é quais tarefas em segundo plano terminam e o que acontece com uma importação quando a memória se esgota.

Existe um limite rígido real. O Immich versão 3 e posteriores requer um x86-64-v2 em hosts amd64, o que abrange a maioria dos processadores vendidos desde aproximadamente 2012. Em hardware mais antigo, o container falha ao arrancar em vez de funcionar mais lentamente.

Se ainda vai fazer a instalação, comece por a instalação completa do Immich numa VPS com Docker Compose e volte aqui para dimensionar o servidor.

Onde a memória é consumida: quatro contentores

O ficheiro Compose oficial inicia quatro serviços. Cada um tem um perfil de consumo de memória diferente, por isso um único valor total oculta a informação útil.

immich-server disponibiliza a interface web e a API e também executa os workers de tarefas em segundo plano. Dois workers ficam dentro desse único contentor. api responde aos pedidos do navegador e da aplicação móvel. microservices executa as filas, incluindo a geração de miniaturas e a codificação de vídeo. As variáveis IMMICH_WORKERS_INCLUDE e IMMICH_WORKERS_EXCLUDE separam esses dois componentes em contentores distintos. Assim, pode atribuir um limite de memória próprio ao componente mais exigente sem limitar o componente que disponibiliza as suas fotografias.

database é uma imagem PostgreSQL 14 com a extensão VectorChord integrada. Armazena todos os metadados e um vetor de pesquisa por recurso. A documentação do Immich define para este serviço o único requisito mínimo explícito da stack: se aplicar limites de recursos do Docker, a base de dados precisa de pelo menos 2 GB. A mesma página indica que a base de dados deve ficar em armazenamento SSD local e nunca numa partilha de rede, porque as pesquisas de vetores e índices são pequenas leituras aleatórias. Num volume de rede, cada leitura transforma-se numa viagem de ida e volta. Se a escolha do plano depender disso, a diferença entre armazenamento NVMe e SSD SATA num VPS é mais importante aqui do que em qualquer outro componente desta stack.

redis executa a imagem Valkey e armazena as filas de tarefas. É, de longe, o menor dos quatro, porque armazena registos de tarefas e não dados de fotografias.

immich-machine-learning é o serviço que determina o tamanho do seu plano. Carrega modelos para pesquisa inteligente, deteção de rostos e reconhecimento de texto, e um modelo carregado permanece residente na memória. MACHINE_LEARNING_MODEL_TTL tem o valor predefinido 300, por isso um modelo é removido após cinco minutos sem pedidos e lido novamente do volume /cache no pedido seguinte. Durante uma importação em massa, nunca existe um intervalo de cinco minutos, por isso os modelos permanecem carregados desde o primeiro recurso até ao último.

O que muda durante uma importação

O Immich ocioso é silencioso. As importações são o momento em que os servidores pequenos falham, porque o carregamento de um recurso coloca uma sequência de tarefas em fila e várias filas são executadas ao mesmo tempo.

A extração de metadados lê o cabeçalho do ficheiro e consome poucos recursos. A geração de miniaturas é mais pesada. O Immich produz 3 saídas de miniatura por recurso: um marcador de posição thumbhash desfocado, uma pré-visualização WebP e uma miniatura JPEG, além de mais uma miniatura por cada rosto detetado. Cada uma dessas tarefas descodifica uma imagem, e a simultaneidade das tarefas determina quantas imagens são descodificadas ao mesmo tempo. A simultaneidade é o multiplicador que transforma um custo pequeno por tarefa num custo para todo o servidor. Por isso, a FAQ do Immich indica-a como o primeiro parâmetro a reduzir numa máquina com recursos limitados. Defina a simultaneidade das filas pesadas como 1 em Administration, Settings, Job Settings.

Os recursos de vídeo acrescentam a transcodificação. Cada tarefa de transcodificação é um processo FFmpeg separado, com a sua própria memória, e utiliza todas as threads de CPU que lhe permitir.

A pesquisa inteligente envia cada recurso novo para o contentor de machine learning, que calcula um vetor de embedding. A deteção de rostos executa um segundo modelo sobre a mesma imagem. Na primeira importação de uma biblioteca de fotografias existente, ambas as filas processam todos os recursos que possui durante horas. Esse é o momento de maior consumo de memória de toda a instalação, e ocorre apenas uma vez.

Por que o reconhecimento facial e de objetos precisa de mais RAM

O processamento facial consiste em duas tarefas. A deteção facial executa um modelo no contentor de machine learning e encontra as caixas delimitadoras. Em seguida, o reconhecimento facial agrupa essas deteções em pessoas e consulta o índice vetorial no Postgres. Por isso, uma biblioteca grande exerce pressão sobre os dois serviços em sequência: primeiro sobre o contentor do modelo durante a deteção e depois sobre a base de dados durante o agrupamento.

Quatro definições alteram o que o contentor de machine learning mantém em memória.

• O modelo facial. O Immich inclui buffalo_l por predefinição, e a FAQ recomenda buffalo_s num servidor pequeno. É um modelo menor, por isso ocupa menos memória e executa mais depressa, mas é menos preciso em rostos pequenos ou vistos de lado.
• O número de workers. MACHINE_LEARNING_WORKERS tem o valor predefinido 1. Cada worker é um processo separado que carrega a sua própria cópia dos modelos. Por isso, aumentar este valor para 2 duplica aproximadamente a memória residente dos modelos. Mantenha-o em 1, a menos que tenha RAM disponível.
• O tamanho do lote. MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION limita o número de rostos processados em simultâneo. Um lote permanece todo em memória, por isso uma fotografia de grupo com quarenta rostos consome mais memória do que um retrato.
• Os tipos de modelos que são executados. A pesquisa inteligente, a deteção facial e o reconhecimento de texto carregam modelos próprios. Desativar os que não utiliza em Administration, Settings, Machine Learning Settings remove a memória que ocupam de forma permanente, e não apenas entre importações.

Existe também MACHINE_LEARNING_MODEL_ARENA, documentado como uma opção que pré-aloca memória de CPU para evitar a fragmentação e que está ativada por predefinição. Altere-a por último. O efeito depende do alocador de memória utilizado. Por isso, a única forma fiável de o avaliar é monitorizar docker stats antes e depois.

Três perfis práticos: 2 GB, 4 GB e 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"
  }
]

Leia estes valores como limites a configurar no Compose, não como medições do consumo do Immich. Um limite é um teto. Não reserva memória nem torna um serviço menor. Define qual serviço o kernel termina quando o servidor fica sem memória. É melhor que essa decisão seja sua, e não o resultado da pontuação interna do kernel.

O servidor de 2 GB: remover o contentor de machine learning

2 GB fica abaixo do mínimo documentado de 6 GB. Portanto, é um compromisso, e deve ser tratado como tal. Comente todo o serviço immich-machine-learning em docker-compose.yml ou mantenha-o em execução e desative todos os modelos em Administration, Settings, Machine Learning Settings. Remover o contentor é a opção mais eficaz, porque um modelo desativado ainda mantém um processo Python residente.

Continuará a ter uploads, álbuns, partilha, cópias de segurança móveis, miniaturas e pesquisa por data, local e nome de ficheiro. Perderá a pesquisa por descrição, o agrupamento automático de rostos em pessoas e o reconhecimento de texto nas imagens.

Os quatro limites somam cerca de 1.7 GB, deixando aproximadamente 300 MB para o host. Note que 768 MB para a base de dados fica abaixo do limite mínimo documentado de 2 GB. Esse é precisamente o compromisso imposto por 2 GB. Por isso, o Postgres é o serviço com maior probabilidade de ser terminado neste cenário.

O primeiro problema surge na importação, não na navegação. Uma biblioteca com dezenas de milhares de fotografias navega de forma aceitável depois de ser importada, porque servir uma página consiste numa consulta de metadados e numa leitura de ficheiro. Uma importação com muitos vídeos fará o mesmo servidor usar swap, porque a transcodificação e a fila de miniaturas precisam de memória ao mesmo tempo. Defina todas as filas pesadas com concorrência 1 e adicione um ficheiro de swap.

O servidor de 4 GB: machine learning ativo, um trabalho de cada vez

4 GB é o menor tamanho em que vale a pena ativar o reconhecimento de rostos e objetos. Limite o contentor de machine learning a 0 MB, altere o reconhecimento facial para buffalo_s e defina a concorrência de trabalhos como 1 para a geração de miniaturas, a deteção de rostos e a pesquisa inteligente.

A primeira passagem por uma biblioteca existente demorará muitas horas e, numa biblioteca grande, mais de um dia. O limite principal é de CPU, não de memória. Por isso, adicionar RAM não encurtará o processo.

Neste cenário, o primeiro problema surge no contentor de machine learning durante essa primeira passagem em massa. Sem limite, o contentor cresce enquanto um trabalho de transcodificação também cresce, e o kernel termina o maior dos dois. Verá Exited (137) em docker ps -a e um contentor reiniciado. A fila ficará silenciosamente mais atrasada do que estava na última verificação.

O servidor de 8 GB: a recomendação documentada

8 GB com 4 cores corresponde ao recomendado pelo Immich. Tudo funciona com as definições predefinidas: pesquisa inteligente, deteção de rostos, reconhecimento de texto e transcodificação, com a concorrência predefinida. Bibliotecas com mais de cem mil recursos funcionam confortavelmente neste cenário. A pressão passa da memória para a velocidade do disco, porque o índice vetorial e as consultas de metadados são as principais tarefas da base de dados durante todo o dia.

Defina os limites na mesma. Num servidor com capacidade disponível, os limites impedem que uma fila descontrolada derrube também a base de dados. Se estiver a comparar este custo com as opções menores, o custo real de um VPS por faixa de memória normalmente faz do plano de 8 GB a forma mais barata de evitar afinações constantes.

Como limitar a memória por serviço com limites do Compose

Não edite docker-compose.yml para isso. Esse ficheiro é substituído sempre que atualiza com wget. Coloque os limites em docker-compose.override.yml, ao lado dele; docker compose faz a fusão automaticamente.

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 deve agora mostrar o limite definido na coluna MEM USAGE / LIMIT, em vez da memória total do host. Se a coluna do limite continuar a mostrar o tamanho total do host, o ficheiro de substituição não foi aplicado. Verifique o nome do ficheiro e execute docker compose config para ver o resultado da fusão.

Um limite demasiado baixo transforma um serviço lento num serviço parado. Aumente-o se um contentor começar a reiniciar continuamente. Consulte como definir limites de memória por serviço no Docker Compose para obter mais informações sobre o funcionamento, incluindo o motivo por que deploy funciona fora do Swarm com o Compose v2.

Como desligar ou mover o container de machine learning

Num servidor pequeno, mover este container para outro local é a maior alteração que pode fazer. O Immich permite executá-lo noutra máquina. Crie este ficheiro no segundo host, que pode ser um desktop ligado apenas à noite:

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

Depois, aceda a Administration, Settings, Machine Learning Settings na interface web, clique em Add URL e introduza http://<host>:3003. Mantenha a mesma versão nos dois hosts, porque a documentação do Immich avisa que as incompatibilidades de versão entre ambos causam erros e instabilidade.

Essa porta transporta as suas fotografias para a outra máquina sem encriptação. Mantenha-a numa rede privada ou utilize um túnel WireGuard entre os dois hosts. Nunca exponha a porta 3003 à internet.

Se o problema for a própria ideia de manter um container de modelos em execução, também é válido comparar as diferenças entre o PhotoPrism e o Immich quanto ao que executam em repouso antes de escolher o tamanho do plano.

De quanto espaço em disco precisa uma biblioteca do Immich?

Não existe um multiplicador único, porque quatro componentes crescem a ritmos diferentes. Eis o cálculo para uma biblioteca com 50,000 fotografias e 500 vídeos curtos.

[
  {
    "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
  }
]

Os valores de 200 GB para fotografias e 60 GB para vídeo são pressupostos. Substitua-os pelas suas próprias médias antes de comprar qualquer equipamento, porque o vídeo determina este valor: um minuto de vídeo de telemóvel ocupa mais espaço do que uma centena de fotografias.

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}'

A linha de 39 GB é o único rácio publicado pelo Immich: as miniaturas geradas e o vídeo transcodificado acrescentam, em média, 10 a 20 por cento ao tamanho da biblioteca. É um intervalo porque depende de quantos dos seus ficheiros são vídeos que precisam de ser recodificados para garantir a compatibilidade com o browser. Uma biblioteca de ficheiros JPEG fica perto do limite inferior desse intervalo.

A base de dados ocupa 3 GB, um custo quase fixo. A documentação do Immich indica que os ficheiros da base de dados ocupam normalmente entre 1 e 3 GB, porque contêm metadados e vetores de pesquisa, não pixels. A cache de modelos ocupa 2 GB e cresce se ativar vários modelos ou testar modelos diferentes. A FAQ identifica este volume como consumidor de espaço precisamente por esse motivo.

As cinco linhas totalizam pouco mais de 300 GB. Assim, um volume de 500 GB deixa espaço para crescer, mas um volume de 250 GB não. Monitorize a distribuição com:

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

Seis pastas ficam sob UPLOAD_LOCATION. upload e library contêm os originais, thumbs contém pré-visualizações e miniaturas de rostos, encoded-video contém cópias recodificadas, profile contém avatares e backups contém dumps automáticos da base de dados. Apenas upload, library e profile são irrecuperáveis, porque todo o restante pode ser regenerado a partir deles.

Há dois aspetos que surpreendem muitas pessoas. Os ficheiros eliminados vão primeiro para a reciclagem e continuam a ocupar espaço até esta ser esvaziada. Por isso, uma limpeza grande não liberta espaço no próprio dia. Além disso, um dump da base de dados contém apenas metadados e não tem utilidade sem os ficheiros:

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

Combine isso com uma cópia ao nível dos ficheiros dos originais para um local fora do servidor. É esse o objetivo de backups restic de um VPS para armazenamento fora do servidor.

A transcodificação usa CPU, não RAM

Adicionar RAM não torna a transcodificação mais rápida. O Immich faz a transcodificação com FFmpeg e, num VPS comum, cada frame é descodificado e codificado pela CPU. Mesmo quando existe aceleração de hardware, a documentação do Immich indica que apenas a codificação é acelerada. A CPU continua a fazer a descodificação por software e o tone mapping.

A aceleração de hardware requer o ficheiro Compose adicional hwaccel.transcoding.yml e um dispositivo para fazer pass-through, usando NVENC, Quick Sync, RKMPP ou VAAPI. A maioria dos planos VPS não disponibiliza nenhum destes recursos. Por isso, planeie a utilização da CPU.

A definição prática é o número de threads. Em Administration, Settings, Video Transcoding Settings, um valor de threads igual a 0 significa usar todos os cores. Isso pode bloquear a interface Web quando um único vídeo é processado num plano com 2 cores. Defina esse valor como 1 ou 2, conforme sugere a FAQ do Immich. Assim, a transcodificação fica lenta, mas não interfere com o serviço.

Por que uma importação em thrashing de swap parece estar bloqueada

Esta é a falha que mais vezes é interpretada incorretamente. Quando o Immich fica sem memória, há dois resultados possíveis, e apenas um deles parece uma falha.

Sem swap, o kernel termina um processo. O container reinicia em segundos, por isso, no browser, a fila de tarefas simplesmente para e depois retoma. As evidências estão em 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) significa que o processo foi terminado com o sinal 9. 137 é 128 mais 9. Um valor OOMKilled de true confirma que o processo foi terminado por falta de memória, e não devido a um crash.

Com swap, nada é terminado e nenhum erro é apresentado. O kernel começa a mover páginas para o disco, a importação fica uma ordem de grandeza mais lenta e a interface web deixa de responder dentro do timeout normal. Todos os containers continuam em execução. Todas as verificações de integridade podem continuar a passar. Parece que o sistema está bloqueado, e é neste ponto que muitas pessoas reiniciam a máquina, perdendo o progresso da fila sem alterar nada.

free -m
vmstat 1 5

Valores diferentes de zero mantidos nas colunas si e so de vmstat significam que a máquina está a ler e a escrever swap continuamente, que é a definição de thrashing. A linha free -m relativa a Swap usado também estará a subir ao mesmo tempo.

Adicione swap mesmo assim numa máquina com 2 GB ou 4 GB, porque uma importação lenta que pode diagnosticar é preferível a um container terminado que não consegue 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

Depois, corrija a causa. Reduza a concorrência das tarefas para 1, limite o container de machine learning ou retire-o deste host. A swap dá-lhe tempo para fazer isso. Por si só, não é a solução.

FAQ

Posso executar o Immich num VPS com 2 GB?

Sim, com o serviço immich-machine-learning comentado em docker-compose.yml e a concorrência de tarefas definida como 1. Isto fica abaixo do mínimo documentado de 6 GB, por isso deve ser tratado como um compromisso conhecido. Continua a ter uploads, álbuns, partilha, cópia de segurança móvel e pesquisa por data, local e nome de ficheiro. Perde a pesquisa por descrição, o agrupamento automático de rostos em pessoas e o reconhecimento de texto dentro das imagens. Adicione um ficheiro de swap de 2 GB para que um pico durante a importação abrande o servidor em vez de provocar a eliminação de um container.

Porque é que a minha importação do Immich para sem apresentar uma mensagem de erro?

Duas causas diferentes parecem idênticas no browser. Um container pode ter sido eliminado por falta de memória; nesse caso, docker ps -a mostra Exited (137) e o container já foi reiniciado. Ou o host pode estar a usar swap; nesse caso, todos os containers continuam em execução e tudo fica simplesmente muito lento. vmstat 1 5 distingue os dois casos: valores diferentes de zero sustentados nas colunas si e so significam que há uso de swap. Em ambos os casos, reduza a concorrência de tarefas para a geração de miniaturas, a deteção de rostos e a pesquisa inteligente.

O que significa o código de saída 137 nos logs do Immich?

137 é 128 mais o sinal 9, portanto o processo foi terminado com SIGKILL. Na prática, isto significa que foi atingido um limite de memória, seja o limite do próprio container, seja porque o host ficou sem memória. Verifique com docker inspect immich_machine_learning | grep -i oomkilled. Um valor de true confirma que o kernel o terminou por falta de memória. Em seguida, free -m e sudo dmesg -T | grep -i oom-kill indicam se o problema foi o limite do container ou todo o host. O container de machine learning é normalmente o afetado, porque costuma conter o processo maior.

De quanto espaço em disco precisa o Immich por fotografia?

Reserve o tamanho do ficheiro original mais 10 a 20 por cento. A documentação do Immich indica que as miniaturas geradas e o vídeo transcodificado aumentam o tamanho da biblioteca em 10 a 20 por cento, em média. A própria base de dados ocupa normalmente 1 a 3 GB, mesmo numa biblioteca grande. O vídeo é o fator que realmente determina o total. Por isso, meça o tamanho médio dos seus ficheiros antes de escolher um plano, em vez de aplicar um multiplicador à quantidade de fotografias.

Preciso de uma GPU para o Immich?

Não. Todas as partes do Immich são executadas na CPU. Uma placa gráfica acelera a inferência dos modelos no container de machine learning e a codificação de vídeo, mas nenhuma das duas é necessária. A maioria dos planos VPS não disponibiliza uma. Em hardware apenas com CPU, defina os threads de transcodificação como 1 ou 2, use o modelo de rostos buffalo_s e deixe a primeira importação em massa ser executada durante a noite.