Immich Self-Hosted Guide: Docker Setup + Shrink Your Photo Library 20–50% With JPEG XL & AV1

Immich is the closest self-hosted equivalent to Google Photos: automatic mobile backup, facial recognition, map view, shared albums, and a timeline fast enough for multi-terabyte libraries. Storage growth has always been the annoying part. Version 3.4.0, released November 10, 2026, shipped one of the project’s most requested features: native JPEG XL support on both the server and the mobile apps.

Below is a clean Docker Compose deployment for Immich v3.4.0, followed by how to convert existing originals to JPEG XL and AV1 with immich-convert-originals so you reclaim 20–50% of your disk space without losing EXIF data, GPS coordinates, favorites, or album links.

What you need

On hardware: an N100/N150 mini PC handles Immich well because the heavy work (thumbnail jobs, ML inference) is bursty, not constant. Our best mini PCs for a home server shortlist has the current picks, and the best NAS for Docker and Proxmox guide covers NAS boxes that double as the host.

Install Immich with Docker Compose

The release ships a compose file; pin the version so you control upgrades:

mkdir -p /opt/immich && cd /opt/immich
wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget https://github.com/immich-app/immich/releases/latest/download/example.env -O .env

Edit .env; the values that matter:

UPLOAD_LOCATION=/mnt/photos/library      # your library disk. big; can be a mounted share
DB_DATA_LOCATION=/opt/immich/postgres    # local disk, SSD preferred. NEVER a network share
TZ=Europe/Bucharest
IMMICH_VERSION=v3.4.0                    # pin it; 'release' floats
DB_PASSWORD=change-me-to-a-long-random-string

The stack runs four containers: immich-server (web UI and API on port 2283), immich-machine-learning (faces and CLIP search embeddings), redis (job queue), and database (PostgreSQL 14 bundled with VectorChord and pgvector for similarity search). Start it up and check status:

docker compose up -d
docker compose ps
curl -sI http://localhost:2283 | head -1    # expect 200 or 302

Open http://server:2283, create the admin account, and install the mobile app, which logs in with your server URL and starts backup on a schedule or on charge. That is the whole Google Photos replacement loop.

A few install notes from the release compose worth knowing:

• UPLOAD_LOCATION can be a mounted share (NFS/SMB); only the database requires local disk.
• Pin IMMICH_VERSION=v3.4.0 instead of release or v3. Immich moves quickly and still ships occasional breaking changes in minor updates, so check release notes before pulling new versions.
• The ML container is the RAM eater. On a 4 GB box you can set IMMICH_MACHINE_LEARNING_ENABLED=false or point it at a bigger machine via MACHINE_LEARNING_URL.
• Hardware transcoding for the transcoded-video preview feature lives in hwaccel.transcoding.yml in the release; Intel iGPU users want the quicksync service.

Remote access

Keep port 2283 off the public internet unless it sits behind TLS. A Caddy reverse proxy takes two lines (photos.example.com { reverse_proxy immich-server:2283 }), or for family-only setups you can leave it closed entirely and connect over Tailscale or self-hosted Headscale. The Immich mobile apps handle Tailscale URLs without trouble.

The storage problem, and what JPEG XL changes

Immich saves originals untouched. A few years of phone photos and 4K clips easily reach 300–800 GB, and camera RAWs push past a few terabytes quickly. Typical savings after conversion:

Standard JPEGs transcode to JPEG XL as a lossless repack, meaning the original JPEG bit stream can be restored byte for byte later. For HEIC photos and H.264 video, savings come from re-encoding with newer codecs.

Prior to v3.4.0, re-encoding existing Immich originals to .jxl broke daily browsing: the server couldn’t build previews cleanly from JXL, and the mobile apps wouldn’t render them natively. With v3.4.0 handling both server previews and client decoding, converting your archive actually stays usable across phones and tablets.

Shrink the library: immich-convert-originals

immich-convert-originals is a self-hosted companion web UI by Fabian Wimberger that batch-converts Immich photos to JPEG XL, HEIC, or AVIF and videos to AV1. It talks directly to Immich’s API: downloads the original asset, encodes locally, uploads the new file, copies metadata, verifies the upload, and trashes the old original.

EXIF tags, GPS data, favorites, ratings, archived state, and album memberships stay mapped to the converted file, and Live Photos remain paired with their video clip. Progress saves to a local SQLite database so interrupted batches resume cleanly, and a dry-run option estimates savings before anything is touched.

Run it in its own Compose file beside your Immich stack:

# /opt/immich-convert/docker-compose.yml
services:
  converter:
    image: ghcr.io/fabianwimberger/immich-convert-originals:latest
    container_name: immich-convert
    ports:
      - "127.0.0.1:8000:8000"   # no built-in auth, keep bound to localhost
    volumes:
      - ./data:/app/data
    restart: unless-stopped

Forward port 8000 over SSH if your server is headless (ssh -L 8000:localhost:8000 user@server) and open http://localhost:8000. Enter your Immich URL (with the /api suffix) and an API key created under your profile icon in Account Settings > API Keys (granting asset read/upload/delete and album scopes, or all temporarily during conversion). Then:

1. Dry-run one album first. Start with a small album to confirm projected space savings and inspect converted previews on desktop and mobile.
2. Convert JPEGs first. JPEG to JXL lossless repacking carries zero quality loss and is fully reversible, making it the lowest-risk win.
3. Batch AV1 video second. CPU AV1 encoding takes hours on large video folders; rely on resumable batches rather than expecting one overnight finish.
4. Pick upload mode vs. local-only. Upload mode swaps originals inside Immich and sends old copies to Immich’s 30-day trash. Local-only writes converted files to <year>/<month> folders on disk without altering your live server if you prefer manual re-import.

If you mostly want smaller videos rather than full format conversion, immich-recompress is the other tool worth knowing: a small dashboard that re-encodes videos via HandBrake (x264/x265/AV1, optional resolution cap) with a review-before-replace step.

The mobile experience problem: HomeRoll

Immich’s official mobile app is solid for scheduled phone backups and admin tasks, though Apple Photos users sometimes miss native iOS gestures when scrolling through old trips. HomeRoll is a native SwiftUI/UIKit Immich client modeled closely after Apple Photos (with companion macOS and Apple TV builds in the same ecosystem).

One practical split is keeping the official Immich client installed for background uploads and management while using HomeRoll as the browsing viewer on iOS. Because HomeRoll is a young MIT-licensed GitHub project installed via sideloading or local builds (AltStore/SideStore), double-check compatibility after Immich server updates before handing it to family members.

Day-2 ops

Updates. Bump IMMICH_VERSION in .env, then run docker compose pull && docker compose up -d. Read the release notes beforehand because major Immich updates occasionally run long PostgreSQL index migrations.

Backups. Immich writes scheduled Postgres dumps to UPLOAD_LOCATION/backups, and v3.4.0 speeds those up using pigz compression when available alongside improved FUTO Backups support. Database dumps alone only protect metadata, albums, and face clusters. Pair them with an off-box restic or rsync copy of UPLOAD_LOCATION itself, since RAID mirrors drive failures rather than accidental deletes.

External libraries. If you have an existing photo archive on disk, mount it read-only into the container and add it as an External Library in the admin settings rather than uploading terabytes through the API.

FAQ

Verdict

With server previews and mobile JPEG XL decoding both working in v3.4.0, self-hosting your photo library no longer forces you to store bloated originals forever. Deploy Immich with a pinned version, let mobile backup settle for a week, and dry-run immich-convert-originals on a test album before touching the rest. Saving 200 to 500 GB on a 1 TB collection delays the next hard drive upgrade considerably.

Related articles

• Best Docker containers for a home server (the rest of the stack)
• Best mini PCs for a home server (the box to run it on)
• Best NAS for Docker & Proxmox homelabs (where the library lives)
• Headscale / Tailscale setup (private access for the mobile app)
• Dokploy backups to Cloudflare R2 (off-box backup pattern)