How to Install Immich on Proxmox: LXC Setup with ZFS Storage

Why Run Immich in an LXC Container on Proxmox?

If you’re running Proxmox and want to self-host a photo backup solution, Immich is the clear frontrunner in 2026. The immediate decision you face is how to deploy it: as a full virtual machine (VM) or a lightweight LXC container. For almost every homelab setup, the LXC route is the better choice.

An LXC container shares the host kernel, which means dramatically lower overhead compared to a VM. You get near-native I/O performance, which matters when Immich is transcoding video or generating ML-based facial recognition thumbnails. More importantly, LXC containers allow direct passthrough of ZFS datasets, giving you efficient storage without the complexity of network mounts or virtual disk files that waste space on snapshots.

This guide walks you through the complete process: automated setup via the Proxmox VE Helper Scripts, the critical ZFS dataset creation, and the one step most guides skip — properly mounting that dataset inside the container so Immich can actually write to it.

Hardware Requirements: What You Need Before Starting

Immich is more resource-hungry than a simple file server. The machine learning features (facial recognition, object tagging, scene classification) are the main drivers of CPU and RAM usage.

For the Proxmox host itself, a modern Intel Core i3 or AMD Ryzen 3 is a comfortable minimum. If you plan to run Immich alongside other services like Plex or a file server, step up to a Core i5 or Ryzen 5. The ML jobs run as background tasks, so they won’t block the UI, but they will consume CPU cycles when active.

Method 1: Automated Install Using Proxmox VE Helper Scripts

The fastest way to get Immich running is through the Proxmox VE Helper Scripts by tteck. This script creates a Debian LXC container, installs Docker inside it, pulls the Immich stack, and configures the basics. It saves you roughly 30–45 minutes of manual configuration.

The Critical Step: Connecting Immich to Your ZFS Storage

This is where most guides fall short. After the container is created, Immich stores all uploaded photos inside the container’s root disk. That’s fine for testing, but for production use, you want your photo library on a dedicated ZFS dataset — it gives you snapshots, compression, and the ability to grow storage without touching the container.

Creating the ZFS Dataset on the Proxmox Host

First, decide where your photo library will live. If you already have a ZFS pool (for example, a mirror or RAIDZ array), create a dedicated dataset for Immich.

zfs create tank/immich
zfs set compression=lz4 tank/immich
zfs set atime=off tank/immich

The compression=lz4 setting is nearly free in terms of CPU overhead and typically saves 20–40% on photo storage. Disabling atime reduces write amplification. If you’re new to ZFS sizing, see our guide on how much storage you need for a NAS to estimate your photo library growth.

Binding the ZFS Dataset into the LXC Container

This is the step that trips everyone up. You cannot simply mount a ZFS dataset inside an unprivileged container without explicitly declaring it in the container’s configuration file.

mp0: /tank/immich,mp=/mnt/immich

Configuring Immich to Use the Mount Point

After the mount is verified, you need to tell Immich where to store its data. The helper script installs Immich via Docker Compose in /opt/immich. Edit the docker-compose.yml file inside the container:

nano /opt/immich/docker-compose.yml

Find the immich-server service’s volumes section. Change the UPLOAD_LOCATION environment variable and the volume mount path to point to your dataset:

environment:
  - UPLOAD_LOCATION=/mnt/immich
volumes:
  - /mnt/immich:/usr/src/app/upload

Save the file and restart the Immich stack: docker compose down && docker compose up -d. Upload a test photo and verify it appears in /mnt/immich/upload from the container’s shell.

Verifying Storage Permissions After Setup

Silent write failures are the most frustrating issue with LXC storage mounts. Immich may report that a photo was uploaded successfully, but the file never actually lands on disk. This happens when the mount point exists but the container lacks write permissions.

Run this quick test from inside the container:

touch /mnt/immich/testfile.txt
ls -la /mnt/immich/testfile.txt
rm /mnt/immich/testfile.txt

If the touch command fails with “Permission denied”, the issue is UID mapping. If it succeeds but the file doesn’t appear on the host’s ZFS dataset, the mount entry in the container config is pointing to the wrong host path. If everything works with test files but Immich still fails to write, check the Docker container’s user — Immich runs as UID 1000 inside the container by default, and that UID must have write access to the mounted directory.

Performance Tuning for Machine Learning Features

Immich’s ML pipeline is the main reason you need more than minimal hardware. If you skip the ML features, you can get away with 4 GB of RAM and 2 cores. But for facial recognition and smart search, allocate at least 8 GB of RAM and 4 cores to the container.

You can adjust these resources on a running LXC container from the Proxmox UI without downtime. Go to the container’s “Resources” tab and change the memory or CPU limit. The changes take effect immediately. If you notice the ML jobs are slow, check the container’s CPU usage with htop — the ML process is single-threaded for most operations, so higher clock speed helps more than additional cores.

For the ZFS dataset, enable the relatime=on property if you’re running ML jobs that read metadata frequently. The default atime=off is fine for most users, but if you notice that Immich’s “recently added” view is slow to populate, switching to relatime can help without the full write penalty of atime.

Bottom Line: LXC with ZFS is the Right Call for Immich

For 90% of Proxmox homelab users, installing Immich in an LXC container with a dedicated ZFS dataset is the optimal setup. You get low overhead, direct filesystem access, and the ability to snapshot your photo library independently of the container OS. The automated helper script gets you to a working install in under 10 minutes, and the storage mount step — the one that causes the most headaches — is a single line in a config file once you know where to put it.

Choose this approach if you want a low-maintenance setup that integrates cleanly with your existing Proxmox storage. If you absolutely need GPU passthrough for hardware-accelerated transcoding, a VM might be necessary, but that adds complexity and overhead that most home users don’t need. Stick with the LXC, set up your ZFS mount correctly, and you’ll have a reliable photo backup system that runs for years.