Immich

Immich is a self-hosted photo and video management solution.

Installation

To install Immich, add the following to your NixOS configuration:

❄︎ /etc/nixos/configuration.nix

services.immich.enable = true;
services.immich.port = 2283;

To access Immich from other devices via network, add the following as well:

❄︎ /etc/nixos/configuration.nix

services.immich.host = "0.0.0.0";
services.immich.openFirewall = true;

More options are available: services.immich.

Tips and Tricks

Custom Media Location

While the official Immich documentation recommends modifying UPLOAD_LOCATION environmental variable for Docker build, NixOS does not support modifying it. Instead, services.immich.mediaLocation may be used, which simply sets IMMICH_MEDIA_LOCATION variable, while this is not recommended in the official documentation:

❄︎ /etc/nixos/configuration.nix

services.immich.mediaLocation = "/var/lib/immich";

⚠︎

Warning: If you have used Immich before, changing this option will completely stop Immich service, disabling access from browser. You may need to reset / remove Postgresql database.

ⓘ︎

Note: If you only need to change the location where raw data is stored, External Libraries may be used.

Enabling Hardware Accelerated Video Transcoding

Add the Immich user to the render and video groups, override the PrivateDevices service config setting to allow the service to access /dev/dri/ and enable Accelerated Video Playback on your system:

❄︎ /etc/nixos/configuration.nix

# `null` will give access to all devices.
# You may want to restrict this by using something like `[ "/dev/dri/renderD128" ]`
services.immich.accelerationDevices = null;

hardware.graphics = { 
 # ...
 # See: https://wiki.nixos.org/wiki/Accelerated_Video_Playback
};

users.users.immich.extraGroups = [ "video" "render" ];

Using Immich behind Nginx

This is a typical Nginx configuration for Immich:

❄︎ /etc/nixos/configuration.nix

services.nginx.virtualHosts."immich.example.com" = {
  enableACME = true;
  forceSSL = true;
  locations."/" = {
    proxyPass = "http://[::1]:${toString config.services.immich.port}";
    proxyWebsockets = true;
    recommendedProxySettings = true;
    extraConfig = ''
      client_max_body_size 50000M;
      proxy_read_timeout   600s;
      proxy_send_timeout   600s;
      send_timeout         600s;
    '';
  };
};

Using borg for backups

Following Immichs backup docs and backup script an automated backup using Borg backup could look something like this:

❄︎ /etc/nixos/configuration.nix

services.borgbackup.jobs."Immich" = {
  paths = config.services.immich.mediaLocation;
  repo = "<path-to-borg-repo>";
  startAt = "Sat 04:00";
  compression = "zstd";
  encryption.mode = "none";
  prune.keep = {
    last = 2;
  };
};

Make sure to manually create a borg repo at the desired location beforehand with sudo borg init --encryption=none <path-to-borg-repo

Troubleshooting

Fixing postgresql database issue after 25.05 upgrade

Postgresql collation version mismatch

After upgrading you might run into an issue like this, leading to immich-server continuously failing and restarting:

Jul 01 14:23:12 server2 immich[178592]: Postgres notice: {
Jul 01 14:23:12 server2 immich[178592]:   severity_local: 'WARNING',
Jul 01 14:23:12 server2 immich[178592]:   severity: 'WARNING',
Jul 01 14:23:12 server2 immich[178592]:   code: '01000',
Jul 01 14:23:12 server2 immich[178592]:   message: 'database "immich" has a collation version mismatch',
Jul 01 14:23:12 server2 immich[178592]:   detail: 'The database was created using collation version 2.39, but the operating system provides version 2.40.',
Jul 01 14:23:12 server2 immich[178592]:   hint: 'Rebuild all objects in this database that use the default collation and run ALTER DATABASE immich REFRESH COLLATION VERSION,>
Jul 01 14:23:12 server2 immich[178592]:   file: 'postinit.c',
Jul 01 14:23:12 server2 immich[178592]:   line: '477',
Jul 01 14:23:12 server2 immich[178592]:   routine: 'CheckMyDatabase'
Jul 01 14:23:12 server2 immich[178592]: }

To fix this, run sudo -u immich psql -d immich and execute these two commands:

ALTER DATABASE immich REFRESH COLLATION VERSION;
REINDEX DATABASE immich;

Upgrading pgvecto.rs

If you still run into issues after restarting postgresql and immich-server services, some additional postgresql database changes might be necessary to upgrade pgvecto.rs table:

Run sudo -u postgres psql and execute consecutively:

CREATE EXTENSION IF NOT EXISTS unaccent; 
CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; 
CREATE EXTENSION IF NOT EXISTS vectors; 
CREATE EXTENSION IF NOT EXISTS cube; 
CREATE EXTENSION IF NOT EXISTS earthdistance; 
CREATE EXTENSION IF NOT EXISTS pg_trgm; 
ALTER EXTENSION vectors UPDATE;
SELECT pgvectors_upgrade();

Finally, restart postgresql and immich: systemctl restart postgresql && systemctl restart immich-server

Immich server too old on NixOS stable

If you encounter errors like Error processing stream or Error in runInIsolateGentle for remote-sync on Android/iOS clients, the cause may be that the Immich server version packaged in nixos-stable is behind the mobile apps.

You can use the Immich package from nixos-unstable while keeping the rest of your system on stable. Add the following to the top of your /etc/nixos/configuration.nix:

let
  unstableTarball = fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-unstable.tar.gz";
in {
  nixpkgs.config = {
    packageOverrides = pkgs: {
      unstable = import unstableTarball {
        config = config.nixpkgs.config;
      };
    };
  };
}

Then override the Immich package in your service config:

services.immich.package = pkgs.unstable.immich;