Immich Complete Self-Hosting Guide: Install, Upgrade, Storage, Backups and GPU Acceleration

By AiCybr Editorial · Published May 21, 2026 · Updated August 12, 2026

Immich is one of the strongest self-hosted alternatives to cloud photo libraries, but a reliable deployment depends much more on storage, database placement and backups than on raw CPU speed.

Current baseline: Immich v3.1.0 is the latest stable release as of August 12, 2026. New Docker Compose installs use the v3 release line. Immich now documents 6 GB RAM minimum and 8 GB recommended, at least 2 CPU cores minimum and 4 recommended, and a Unix-compatible filesystem. Since v3, the amd64 machine-learning image also requires x86-64-v2 CPU support. Older CPUs that cannot provide that instruction-set level cannot use the current v3 machine-learning container. Immich requirements · v3.1.0 release

Recommended architecture at a glance

For most home servers, a dependable layout looks like this:

The key rule is simple: do not treat Immich itself as your only backup of your photos. Immich recommends a 3-2-1 strategy and explicitly requires separate protection of both the database and the media filesystem.

What changed from older Immich guides

A lot of Immich advice written for v1 or early v2 is now stale. The most important current differences are:

• v3 is the current major release line; the old v2.7.5 baseline is obsolete.
• Current official requirements list 6 GB minimum RAM, not 4 GB for a normal deployment. Immich says 4 GB can work only with machine-learning features disabled.
• docker compose is required; the legacy docker-compose command is deprecated and unsupported by Immich.
• New v3 amd64 machine-learning deployments require x86-64-v2.
• Database backup and restore changed materially in v2.5.0 and now includes web-based restore workflows and maintenance mode.
• Database backups are stored under UPLOAD_LOCATION/backups, but they contain metadata only, not originals.
• New installations do not necessarily put original uploads in library/; with Storage Template disabled, originals are normally under upload/<userID>.

These changes are important enough that upgrading an old guide by changing only the version number would be misleading.

1. Current Immich service layout

The official v3.1.0 Compose file runs four core services:

The current Compose file mounts ${UPLOAD_LOCATION} into the server container and ${DB_DATA_LOCATION} into PostgreSQL. Hardware acceleration is optional and configured separately for video transcoding and machine learning.

Do not casually replace individual images, database extensions or Compose fragments with snippets from old blog posts. Immich explicitly warns users to use the Compose file shipped with the current release because the file on the repository’s main branch may not match the latest stable release.

2. Hardware requirements: what actually matters

Official minimums

Immich currently documents:

For large libraries, imports and ML processing, more CPU and RAM can reduce processing time, but there is no universal official requirement such as “32 GB for 500,000 photos.” Size the machine around concurrency, video transcoding, machine-learning jobs and whatever else shares the host.

Older x86 hardware and Immich v3

This is one of the easiest upgrade traps to miss. Immich v3’s machine-learning image on amd64 requires x86-64-v2. Immich says most CPUs from roughly 2012 onward support it, but virtual machines can still expose an older virtual CPU profile.

If a v3 upgrade fails on the machine-learning container, check the CPU model presented to the VM before assuming the container image is broken. Immich identifies v2.7.5 as the last version supporting x86-64-v1, but that release is no longer supported.

3. Storage design: database and media should be treated differently

Keep PostgreSQL off network shares

DB_DATA_LOCATION should normally be on a local SSD. Immich’s requirements explicitly state that network shares are unsupported for the database. On Windows, the database must also live on a filesystem with proper Unix-style ownership and permissions; NTFS/exFAT host mounts are not suitable for PostgreSQL data.

A practical layout is:

Local SSD / NVMe
├── Immich PostgreSQL data
├── Docker / OS
└── optional thumbnails / ML cache

Large local disk / storage array
└── Immich UPLOAD_LOCATION

Original media can consume many terabytes, while the database is usually much smaller. That makes it reasonable to spend fast local SSD capacity on PostgreSQL while keeping originals on high-capacity storage.

Understand where originals actually live

Do not assume every original is in UPLOAD_LOCATION/library.

With Storage Template off, current Immich documentation says uploaded originals are stored under:

UPLOAD_LOCATION/upload/<userID>

With Storage Template on, originals are moved into:

UPLOAD_LOCATION/library/<userID>

Other important directories include:

UPLOAD_LOCATION/profile/
UPLOAD_LOCATION/thumbs/
UPLOAD_LOCATION/encoded-video/
UPLOAD_LOCATION/backups/

thumbs and encoded-video are generated data and can be recreated. Originals, profile assets and the database are not safely reproducible from Immich alone.

4. Install Immich with the supported Docker Compose path

The safest approach is to follow Immich’s release-provided files rather than maintain a hand-written Compose stack.

Create a directory:

mkdir -p ~/immich-app
cd ~/immich-app

Download the current release files:

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

Review .env. Current official examples use settings such as:

UPLOAD_LOCATION=./library
DB_DATA_LOCATION=./postgres
IMMICH_VERSION=v3
DB_PASSWORD=replace_with_a_random_alphanumeric_password
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Immich currently recommends keeping the database password alphanumeric to avoid Docker parsing problems.

Start the stack:

docker compose up -d

Then open:

http://SERVER-IP:2283

Before importing a large library, configure backups and verify where both UPLOAD_LOCATION and DB_DATA_LOCATION physically reside.

5. Backup Immich correctly

A usable Immich backup has two independent parts:

1. the PostgreSQL database;
2. the files under UPLOAD_LOCATION that contain your originals and other needed assets.

Backing up only one is insufficient.

Automatic database backups

Immich creates automatic database dumps under:

UPLOAD_LOCATION/backups

The schedule and retention can be managed in the web interface. Current defaults documented by Immich are daily backups at 2:00 AM with the latest 14 retained.

That is useful for disaster recovery, but these dumps contain metadata only. They do not include your photos or videos.

Media backup

Immich recommends backing up the entire UPLOAD_LOCATION. If space is constrained, the critical original-data locations depend on whether Storage Template is enabled, but the safest operational rule is to protect the whole upload tree.

Do not modify files inside Immich’s managed directories directly. Current documentation warns that deleting or editing files behind Immich’s back can produce missing assets or checksum mismatches.

Keep database and files reasonably synchronized

The cleanest backup is taken while the Immich server is stopped so neither side changes during the snapshot.

If downtime is unacceptable, Immich recommends:

1. back up the database first;
2. back up the filesystem second.

That ordering is safer because a restored filesystem can contain extra files the older database does not know about. The opposite ordering can leave the restored database referencing files that were not captured.

6. Restore strategy: test it before you need it

Current Immich supports web-based restoration as well as command-line recovery.

For a fresh installation, the current restore flow can detect database dumps under the restored upload path and present Restore from backup during onboarding. Immich performs storage integrity checks and can run migrations during restore.

For an existing installation, database restore is available through the Administration maintenance interface.

Important caveats:

• restoring a database replaces the current database;
• backups made on different Immich versions may require migrations;
• the restore process changed in v2.5.0;
• files from the matching backup must be restored too;
• external-library mount paths need to remain consistent or be remapped deliberately.

A backup that has never been restored is only an assumption. Periodically test recovery on a spare VM or isolated host.

7. Upgrade Immich safely

Before an upgrade:

1. verify that your database backup completed;
2. verify that original media is independently protected;
3. read release notes for breaking changes;
4. confirm CPU compatibility if crossing into v3;
5. use the Compose and .env expectations for the target release.

A typical Compose update is:

docker compose pull
docker compose up -d

For major-version jumps, do not blindly reuse old Compose snippets. The official release package is the source of truth.

After upgrading, check:

docker compose ps
docker compose logs --tail=200 immich-server

Also confirm that the web UI loads, mobile uploads work, thumbnails render and recent database backups are being created.

8. GPU and hardware acceleration

Immich does not require a discrete GPU. CPU-only operation is valid.

There are two separate acceleration decisions:

• video transcoding for media playback/compatibility;
• machine-learning inference for facial recognition and semantic features.

The official v3.1 Compose comments expose different hardware paths for each. Current machine-learning image variants include cuda, rocm, openvino, armnn and rknn; transcoding options include NVENC, Quick Sync, VAAPI and platform-specific paths.

Do not buy a GPU solely because an old guide names a specific gaming card as “recommended.” For many home deployments, Intel Quick Sync or another supported integrated accelerator is enough for video work, while ML jobs can run on CPU if processing speed is acceptable.

Use Immich’s current hardware-acceleration documentation for the exact Compose extension required by your platform: Hardware transcoding · ML acceleration

9. Reverse proxy and remote access

Immich listens on port 2283 by default. For LAN-only use, exposing that port directly on a trusted network may be sufficient.

For remote access, place Immich behind a properly configured HTTPS reverse proxy or a private-overlay network rather than opening the administration surface indiscriminately to the internet.

Whichever proxy you use, preserve the normal client IP/header behavior recommended by both the proxy and Immich, and make sure large video uploads are not blocked by proxy request-size or timeout defaults.

A reverse proxy is not a backup, authorization system or intrusion-prevention system. Keep Immich patched and restrict unnecessary network exposure.

10. NAS, VM and Windows deployment notes

NAS

Running Immich on a NAS can be sensible when the NAS already provides reliable local storage and Docker/VM capability. Keep the PostgreSQL volume on storage with correct filesystem semantics and low latency. Avoid putting DB_DATA_LOCATION on an SMB/NFS share simply because the media library is network-backed.

Virtual machines

Immich explicitly supports full virtual machines. If v3 machine learning fails on otherwise-modern hardware, ensure the hypervisor passes through an x86-64-v2-capable CPU model rather than an old compatibility profile.

Windows

Immich can run through Docker Desktop or WSL2, but Linux remains the recommended server platform. The PostgreSQL data path must not sit on an NTFS/exFAT bind mount. Immich’s documentation recommends a Docker-managed volume when Windows filesystem semantics are a problem.

11. Recommended production checklist

Before trusting Immich with a large photo library, verify all of these:

• Current supported Immich release is deployed.
• docker compose, not legacy docker-compose, is used.
• Host has at least the current documented memory/CPU baseline.
• v3 amd64 host/VM exposes x86-64-v2 support.
• PostgreSQL data is on supported local storage.
• UPLOAD_LOCATION capacity includes room for generated thumbnails and video transcodes.
• Automatic database backups are enabled and visible.
• Media files are backed up independently of Immich.
• At least one backup copy is outside the Immich host/storage failure domain.
• Restore procedure has been tested.
• Remote access uses HTTPS or a private network path.
• GPU acceleration is configured only if the workload benefits from it.

Bottom line

For most users, the best Immich server is not the machine with the biggest GPU. It is the machine with reliable storage, local PostgreSQL, enough RAM, current supported software, and a backup plan that has actually been tested.

A small modern x86 or ARM server can handle a normal household library well. Spend first on dependable storage and backups. Add faster CPUs or hardware acceleration when imports, facial recognition or video transcoding become bottlenecks.

The two most important operational rules are unchanged regardless of hardware: keep the database on supported local storage, and back up both the database and the actual media files.

Primary references

• Immich requirements
• Immich Docker Compose installation
• Immich backup and restore
• Immich system integrity
• Immich v3.1.0 release
• Immich v3.1.0 Compose file