Immich RAM na disk: how much you really need

Immich bezwen RAM konbyen?

Immich mande 6 GB RAM (random access memory) na documented minimum, and e recommend 8 GB. E need 2 CPU cores for the low end and 4 for install wey go work comfortably. This figure cover the whole stack, because Immich na four containers, no be one application. To browse library wey don already import no dey use plenty resources. Importing na where memory dey go, and most of am dey go one container wey you fit switch off.

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

Na the published figures from Immich requirements page as of August 2026. Dem na sizing recommendation, no be check wey software dey run for startup. Immich fit start with less resources. For smaller server, wetin change na which background jobs go finish and wetin import go do when memory finish.

One real hard limit dey. Immich version 3 and later need an x86-64-v2 CPU for amd64 hosts. This cover most processors wey dem sell since roughly 2012. For older hardware, the container go fail to start instead of just running slowly.

If you never start the install, begin with full Immich install for VPS with Docker Compose, then come back here to size the box.

Memory dey go where: containers four

The official Compose file dey start services four. Each one get different memory pattern, so one total number dey hide the useful part.

immich-server dey serve web interface and API, and e dey also run background job workers. Workers two dey inside that one container. api dey answer requests from browser and mobile app. microservices dey run queues, including thumbnail generation and video encoding. Variables IMMICH_WORKERS_INCLUDE and IMMICH_WORKERS_EXCLUDE dey split those two into separate containers. Na so you fit give the noisy half e own memory limit without capping the half wey dey serve your photos.

database na PostgreSQL 14 image wey get VectorChord extension built inside. E dey hold all metadata and one search vector for each asset. Immich docs give this service the only explicit minimum for the whole stack: if you apply Docker resource limits, database need at least 2 GB. The same page talk say database must dey on local SSD storage, and never on any network share, because vector and index lookups na small random reads. Network volume go turn each lookup into round trip. If plan choice depend on this, the difference between NVMe and SATA SSD storage for VPS matter pass for here than anywhere else for this stack.

redis dey run Valkey image and hold job queues. E small pass the other three by far, because e dey store job records instead of photo data.

immich-machine-learning na the service wey dey decide your plan size. E dey load models for smart search, face detection, and text recognition. Once model load, e dey remain inside memory. MACHINE_LEARNING_MODEL_TTL default na 300, so model go comot after five minutes without requests, then e go read am again from /cache volume when the next request come. During bulk import, five-minute gap no dey happen, so models remain loaded from the first asset reach the last one.

Wetin dey change during import

When Immich dey idle, e quiet. Import na where small servers fit crash, because uploading one asset dey queue a chain of jobs, and several queues dey run at the same time.

Metadata extraction dey read the file header, and e light. Thumbnail generation heavier. Immich dey produce three thumbnail outputs for each asset: one blurred thumbhash placeholder, one WebP preview, and one JPEG thumbnail. E still produce one extra thumbnail for every face wey e detect. Each job dey decode an image, and job concurrency decide how many images dem go decode at once. Concurrency na the multiplier wey turn small cost for each job into cost across the whole server. Na why Immich FAQ call am the first thing to reduce for machine wey get limited resources. Set concurrency for the heavy queues to 1 under Administration, Settings, Job Settings.

Video assets add transcoding. Each transcode job na separate FFmpeg process with its own memory, and e go use every CPU thread wey you allow am.

Smart search dey send every new asset go the machine learning container to calculate one embedding vector. Face detection dey run a second model over the same image. During the first import of an existing photo library, both queues dey run over every asset wey you get, for hours. Na this be the worst time for memory for the whole installation, and e happen only once.

Why face and object recognition need the most RAM

Face handling na two jobs. Face detection dey run model for the machine learning container and find the boxes. Facial recognition then group those detections into people, and that step dey query the vector index for Postgres. So large library dey put pressure on both services one after another: model container when detection dey run, then database when grouping dey run.

Four settings dey change wetin machine learning container dey hold.

• The face model. Immich dey ship buffalo_l by default, and FAQ dey recommend buffalo_s for small server. E na smaller model, so e dey use less memory and run faster, but accuracy fit reduce for small faces or faces wey turn sideways.
• The worker count. MACHINE_LEARNING_WORKERS default na 1. Each worker na separate process wey load im own copy of the models, so if you raise am to 2, resident model memory go roughly double. Leave am for 1 unless you get RAM wey you no dey use.
• The batch size. MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION dey limit how many faces dem fit process at once. Batch dey stay for memory together, so group photo with forty faces go use more memory pass portrait.
• Which model types dey run at all. Smart search, face detection, and text recognition each load im own models. If you turn off the ones you no use under Administration, Settings, Machine Learning Settings, dem memory go comot permanently instead of only between imports.

You also get MACHINE_LEARNING_MODEL_ARENA, wey documentation describe as setting aside CPU memory early to prevent fragmentation, and e dey on by default. Change am last. The effect depend on the memory allocator underneath, so the only correct way to judge am na to monitor docker stats before and after.

Three worked profiles: 2 GB, 4 GB and 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"
  }
]

Read dem as limits wey you go put for Compose, no be measurement of wetin Immich dey use. Limit na upper ceiling. E no reserve anything, and e no make service smaller. E decide which service kernel go kill when the box memory finish. Na decision wey better make by yourself instead of leaving am to kernel own scoring.

The 2 GB box: remove the machine learning container

2 GB dey below the documented minimum of 6 GB, so na compromise be this, and e good make we call am that. Comment out the whole immich-machine-learning service for docker-compose.yml, or leave am running and disable every model under Administration, Settings, Machine Learning Settings. Removing the container na stronger option, because disabled model still leave Python process resident.

You still get uploads, albums, sharing, mobile backup, thumbnails, and search by date, place and filename. You lose search by description, automatic grouping of faces into people, and text recognition inside images.

The four limits together na about 1.7 GB, so host get roughly 300 MB left. Note say 768 MB for the database dey below the documented 2 GB floor. Na exactly the compromise wey 2 GB force, and na why Postgres most likely be the service wey go get killed here.

The import go fail first, no be browsing. Library wey get low tens of thousands of photos dey browse well enough after e enter, because serving page na metadata query plus file read. Video-heavy import for the same box go use swap, because transcode and thumbnail queue need memory at the same time. Set every heavy queue to concurrency 1 and add swap file.

The 4 GB box: machine learning on, one job at a time

4 GB na the smallest size wey face and object recognition make sense to switch on. Limit the machine learning container to 0 MB, switch facial recognition to buffalo_s, and set job concurrency to 1 for thumbnail generation, face detection and smart search.

The first pass over existing library go run for many hours, and for large library e fit pass one day. Na CPU limit be this, no be memory limit, so more RAM no go make am finish faster.

The machine learning container go fail first during that first bulk pass. If you no set limit, e go grow while transcode job dey grow too, and kernel go kill the bigger one. You go see Exited (137) for docker ps -a and container wey restart, while queue quietly dey further behind than when you last check am.

The 8 GB box: the documented recommendation

8 GB with 4 cores match wetin Immich recommend, and everything go run with default settings: smart search, face detection, text recognition and transcoding, with default concurrency. Libraries wey pass one hundred thousand assets dey comfortable here. The pressure go shift from memory to disk speed, because vector index and metadata queries na wetin database dey handle all day.

Set the limits anyway. For box wey get enough room, limits stop one runaway queue from bringing database down with am. If you dey compare the price with smaller options, wetin VPS really cost by memory tier usually make 8 GB plan the cheapest way to stop tuning.

Service per Compose limits dey cap memory

No edit docker-compose.yml for this. wget dey replace that file every time you upgrade. Put the limits for docker-compose.override.yml beside am, because docker compose dey merge am automatically.

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 suppose don show your memory ceiling for MEM USAGE / LIMIT column instead of the host total memory. If the limit column still dey show the full host size, e mean say override file no enter: check the file name and run docker compose config to see the merged result.

Limit wey too low fit turn slow service to dead service, so increase am if container dey restart repeatedly. You fit read more about how e work for setting memory limits per service for Docker Compose, including why deploy dey work outside Swarm with Compose v2.

How to turn off or move the machine learning container

For small server, to move this container go another place na the biggest single change wey you fit make. Immich support running am for another machine. Create this file for the second host. E fit be desktop wey dey on only for evening:

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

Then go Administration, Settings, Machine Learning Settings for the web interface. Click Add URL, then enter http://<host>:3003. Make the version for both hosts remain the same, because Immich docs warn say version mismatch between dem fit cause bugs and instability.

That port dey carry your photos go the other machine without encryption. So keep am for private network, or run am through a WireGuard tunnel between the two hosts. Never expose 3003 to internet.

If na the resident model container itself be the problem, that one still be valid reason to compare how PhotoPrism and Immich differ for wetin dem run when dem dey idle before you commit to a plan size.

Disk space Immich library need na how much?

No be one multiplier fit work for every case, because four different things dey grow at four different rates. See the calculation for library wey get 50,000 photos and 500 short videos.

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

The 200 GB photos and 60 GB video na assumptions. Replace dem with your own averages before you buy anything, because video na the main thing wey decide this number: one minute of phone video bigger pass one hundred photos.

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

The 39 GB row na the only published ratio wey Immich provide: generated thumbnails and transcoded video add 10 to 20 percent to the library size on average. E be range because e depend on how many of your assets be video wey need re-encoding for browser compatibility. Library wey mostly get JPEGs go dey near the bottom of that range.

The database na 3 GB, and this one nearly be fixed cost. Immich document database files as typically 1 to 3 GB, because dem hold metadata and search vectors, no be pixels. The model cache na 2 GB, and e go grow if you enable several models or test different ones. The FAQ flag this volume as space consumer for exactly that reason.

The five rows add up to small pass 300 GB, so 500 GB volume leave room to grow, but 250 GB volume no go. Monitor the split with:

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

Six folders dey under UPLOAD_LOCATION. upload and library hold the originals, thumbs hold previews and face thumbnails, encoded-video hold re-encoded copies, profile hold avatars, and backups hold automatic database dumps. Na only upload, library and profile no fit replace, because everything else fit regenerate from dem.

Two things dey surprise people. Deleted assets first go trash and keep their space until you empty the trash, so big cleanup no go free any space on the same day wey you do am. And database dump na metadata only, so e no get value without the files:

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

Combine this with file level copy of the originals to somewhere outside the server. Na wetin restic backups from VPS go off-server storage dey for.

Transcoding dey use CPU, no be RAM

Adding RAM no go make transcoding faster. Immich dey use FFmpeg for transcoding, and for ordinary VPS, na CPU dey decode and encode every frame. Even when hardware acceleration dey available, Immich documentation talk say na encoding only e dey accelerate. So CPU still dey do software decoding and tone mapping.

Hardware acceleration need the extra hwaccel.transcoding.yml Compose file plus device wey you go pass through, using NVENC, Quick Sync, RKMPP or VAAPI. Most VPS plans no get any of these, so plan to use CPU.

The practical setting na thread count. Under Administration, Settings, Video Transcoding Settings, thread value of 0 mean all cores. This fit make one video freeze the web interface for a 2 core plan. Set the value to 1 or 2 there, as Immich FAQ recommend. This go make transcoding slow instead of disrupting the service.

Why swap thrashing import dey look like hang

This na the failure wey people dey misunderstand pass. When Immich memory finish, two things fit happen, and na only one go look like failure.

Without swap, kernel go kill one process. Container go restart within seconds, so for browser, job queue just stop temporarily, then continue. Evidence dey for 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) mean say process dem kill am with signal 9. 137 na 128 plus 9. An OOMKilled value of true confirm say memory cause the kill, no be crash.

With swap, nothing dey get killed and no error dey happen. Kernel start moving pages go disk, import slow down by one order of magnitude, and web interface stop answering within normal timeout. Every container still dey run. Every health check fit still pass. E go look like hang, and people dey reboot the box for this point, wey go make queue progress lost and no change anything.

free -m
vmstat 1 5

Non-zero values wey continue for si and so columns of vmstat mean say machine dey read and write swap continuously. Na this be the definition of thrashing. The free -m row for Swap used go dey increase at the same time.

Add swap anyway for 2 GB or 4 GB box, because slow import wey you fit diagnose better pass container wey dem kill and you no fit diagnose:

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

Then fix the cause. Reduce job concurrency to 1, limit the memory for machine learning container, or remove am from this host. Swap go give you time to do this. E no be the complete answer by itself.

FAQ

I fit run Immich for a 2 GB VPS?

Yes, if you comment out the immich-machine-learning service for docker-compose.yml and set job concurrency to 1. This dey below the documented minimum of 6 GB, so treat am as known compromise. You still get uploads, albums, sharing, mobile backup, and search by date, place, and filename. You no go get search by description, automatic grouping of faces into people, or text recognition inside images. Add a 2 GB swap file so import spike go only slow the server instead of making container get killed.

Why Immich import dey stop without error message?

Two different causes fit look the same from browser. Either memory kill container, and for that case docker ps -a go show Exited (137) while the container don already restart, or host dey swap, and for that case every container still dey run but everything just dey very slow. vmstat 1 5 go separate the two: non-zero numbers wey continue for si and so columns mean say swapping dey happen. Lower job concurrency for thumbnail generation, face detection, and smart search for either case.

Wetin exit code 137 mean for Immich logs?

137 na 128 plus signal 9, so SIGKILL kill the process. For practice, this mean say memory ceiling don reach, either the container own limit or host don run out of memory. Check am with docker inspect immich_machine_learning | grep -i oomkilled. If true get value, e confirm say kernel kill am because of memory, while free -m plus sudo dmesg -T | grep -i oom-kill go show whether na container limit or the whole host cause am. The machine learning container na the usual victim because e normally be the largest process.

How much disk space Immich need for each photo?

Plan for the original file plus 10 to 20 percent. Immich documentation talk say generated thumbnails and transcoded video increase library size by 10 to 20 percent on average, while the database itself normally dey use 1 to 3 GB even for large library. Video na the thing wey really determine your total, so measure your own average file size before you choose plan instead of applying multiplier to photo count.

I need GPU for Immich?

No. Every part of Immich fit run for CPU. Graphics card go make model inference for the machine learning container and video encoding faster, but you no need either one. Most VPS plans no dey offer GPU. For CPU-only hardware, set transcoding threads to 1 or 2, use the buffalo_s face model, and allow the first bulk import run overnight.