Immich

https://docs.immich.app/
Admin
Immich is a self-hosted photo and video backup solution, designed to help users manage and store...
Tokens:92,575
Snippets:844
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quick-start DevPod with Docker

Source: https://docs.immich.app/developer/devcontainers

Quick-start guide for DevPod with Docker: clone the repository, add and use the Docker provider, build the dev image, and start the devcontainer.

```bash
# Step 1: Clone the Repository  

git clone https://github.com/immich-app/immich.git  

cd immich  

  

# Step 2: Prepare DevPod (if you haven't already)  

devpod provider add docker  

devpod provider use docker  

  

# Step 3: Build 'immich-server-dev' docker image first manually  

docker build -f server/Dockerfile.dev -t immich-server-dev .  

  

# Step 4: Now you can start devcontainer  

devpod up .  

```

--------------------------------

### Run the Immich install script

Source: https://docs.immich.app/install/script

Downloads and runs the install script from the Immich repository. The script downloads docker-compose.yml and .env from the main branch and starts the containers. Requires Linux and Docker.

```bash
curl -o- https://raw.githubusercontent.com/immich-app/immich/main/install.sh | bash
```

--------------------------------

### Start web dev server with demo backend

Source: https://docs.immich.app/developer/setup

Shorthand to start the web dev server connected to the hosted demo server (https://demo.immich.app/).

```bash
mise //web:start-demo
```

--------------------------------

### Start development server with mise dev

Source: https://docs.immich.app/developer/setup

Starts the development server for the Immich project from the repo root. All services are started with hot-reloading enabled.

```bash
mise dev
```

--------------------------------

### Install Immich CLI with npm

Source: https://docs.immich.app/features/command-line-interface

Installs the Immich CLI globally via npm. Requires Node.js 22 or above and npm.

```bash
npm i -g @immich/cli
```

--------------------------------

### Connect web to remote backend with IMMICH_SERVER_URL

Source: https://docs.immich.app/developer/setup

Starts the web dev server connected to a remote backend. Sets the IMMICH_SERVER_URL environment variable to the demo server URL and runs the web start task.

```bash
IMMICH_SERVER_URL=https://demo.immich.app/ mise //web:start
```

--------------------------------

### Set IMMICH_SERVER_URL in PowerShell and start web

Source: https://docs.immich.app/developer/setup

PowerShell alternative for setting the IMMICH_SERVER_URL environment variable before starting the web dev server.

```powershell
$env:IMMICH_SERVER_URL = "https://demo.immich.app/"

mise //web:start
```

--------------------------------

### Start SSH Agent and Add SSH Key

Source: https://docs.immich.app/developer/devcontainers

Starts the SSH agent on the host machine and adds your SSH key so that VS Code can forward it to the Dev Container for GitHub access.

```bash
eval "$(ssh-agent -s)"  

ssh-add ~/.ssh/id_rsa  # or your key path  

```

--------------------------------

### Start Flutter widget previewer

Source: https://docs.immich.app/developer/setup

Launches Flutter's Widget Previewer to inspect shared design-system widgets in isolation with a light/dark toggle and hot reload.

```bash
cd mobile/packages/ui

flutter widget-preview start
```

--------------------------------

### Run e2e test environment

Source: https://docs.immich.app/developer/testing

Starts a test production environment for running end-to-end tests. Run this before executing the e2e tests.

```bash
mise e2e  
```

--------------------------------

### Caddy reverse proxy config

Source: https://docs.immich.app/administration/reverse-proxy

Minimal Caddyfile example for reverse proxying to Immich with automatic HTTPS. Replace `immich.example.org` with your domain and `<snip>` with the backend address.

```caddy
immich.example.org {  

    reverse_proxy http://<snip>:2283  

}  

```

--------------------------------

### docker-compose-pgadmin.yml for pgAdmin

Source: https://docs.immich.app/guides/database-gui

Add this file next to your docker-compose.yml to run pgAdmin alongside Immich. Change the PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD values. Start with `docker compose -f docker-compose.yml -f docker-compose-pgadmin.yml up`.

```yaml
name: immich  

  

services:  

  pgadmin:  

    image: dpage/pgadmin4  

    container_name: pgadmin4_container  

    restart: always  

    ports:  

      - "8888:80"  

    environment:  

      PGADMIN_DEFAULT_EMAIL: admin@example.com  

      PGADMIN_DEFAULT_PASSWORD: strong-password  

    volumes:  

      - pgadmin-data:/var/lib/pgadmin  

  

volumes:  

  pgadmin-data:  
```

--------------------------------

### Get embedding dimension size for manual migration

Source: https://docs.immich.app/administration/postgres-standalone

Run this SQL command while pgvecto.rs is still installed to get the dimension size of the embedding column in the smart_search table. Note the number outputted, as it is needed later in the manual migration.

```sql
SELECT atttypmod as dimsize  

    FROM pg_attribute f  

    JOIN pg_class c ON c.oid = f.attrelid  

    WHERE c.relkind = 'r'::char  

    AND f.attnum > 0  

    AND c.relname = 'smart_search'::text  

    AND f.attname = 'embedding'::text;  


```

--------------------------------

### Initialize Borg repositories (local and remote)

Source: https://docs.immich.app/guides/template-backup-script

Run these commands once to set up the Borg repositories. Set UPLOAD_LOCATION to the Immich database location from your .env file, BACKUP_PATH to the local backup directory, and REMOTE_HOST/REMOTE_BACKUP_PATH for the remote machine. Uses --encryption=none.

```shell
UPLOAD_LOCATION="/path/to/immich/directory"       # Immich database location, as set in your .env file  

BACKUP_PATH="/path/to/local/backup/directory"  

  

mkdir "$UPLOAD_LOCATION/database-backup"  

borg init --encryption=none "$BACKUP_PATH/immich-borg"  

  

## Remote set up  

REMOTE_HOST="remote_host@IP"  

REMOTE_BACKUP_PATH="/path/to/remote/backup/directory"  

  

borg init --encryption=none "$REMOTE_HOST:$REMOTE_BACKUP_PATH/immich-borg"  
```

--------------------------------

### Download example.env as .env with wget

Source: https://docs.immich.app/install/docker-compose

Downloads the example.env file and saves it as .env in the current directory.

```bash
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env  
```

--------------------------------

### immich upload JSON output with jq

Source: https://docs.immich.app/features/command-line-interface

Get JSON output with keys `newFiles`, `duplicates`, and `newAssets` using `--json-output`. Due to logging output, strip the first three lines (here `tail -n +6` is used) to get valid JSON; this example pipes to `jq .newFiles[]` to list files that would be uploaded.

```bash
immich upload --dry-run --json-output . | tail -n +6 | jq .newFiles[]  

```

--------------------------------

### Uninstall legacy Immich CLI

Source: https://docs.immich.app/features/command-line-interface

Uninstalls the legacy Immich CLI before installing the new one. Required if you previously installed the legacy CLI.

```bash
npm uninstall -g immich
```

--------------------------------

### immich upload command help

Source: https://docs.immich.app/features/command-line-interface

Displays the help for the `immich upload` command, listing all upload-specific arguments and options. Options can be set via environment variables as noted. Defaults include recursive=false, concurrency=4, and dry-run=false.

```bash
Usage: immich upload [paths...] [options]  

  

Upload assets  

  

Arguments:  

  paths                       One or more paths to assets to be uploaded  

  

Options:  

  -r, --recursive             Recursive (default: false, env: IMMICH_RECURSIVE)  

  -i, --ignore <pattern>      Pattern to ignore (env: IMMICH_IGNORE_PATHS)  

  -h, --skip-hash             Don't hash files before upload (default: false, env: IMMICH_SKIP_HASH)  

  -H, --include-hidden        Include hidden folders (default: false, env: IMMICH_INCLUDE_HIDDEN)  

  -a, --album                 Automatically create albums based on folder name (default: false, env: IMMICH_AUTO_CREATE_ALBUM)  

  -A, --album-name <name>     Add all assets to specified album (env: IMMICH_ALBUM_NAME)  

  --visibility <visibility>   Set the visibility of uploaded assets (choices: "archive", "timeline", "hidden", "locked", env: IMMICH_VISIBILITY)  

  -n, --dry-run               Don't perform any actions, just show what will be done (default: false, env: IMMICH_DRY_RUN)  

  -c, --concurrency <number>  Number of assets to upload at the same time (default: 4, env: IMMICH_UPLOAD_CONCURRENCY)  

  -j, --json-output           Output detailed information in json format (default: false, env: IMMICH_JSON_OUTPUT)  

  --delete                    Delete local assets after upload (env: IMMICH_DELETE_ASSETS)  

  --delete-duplicates         Delete local assets that are duplicates (already exist on server) (env: IMMICH_DELETE_DUPLICATES)  

  --no-progress               Hide progress bars (env: IMMICH_PROGRESS_BAR)  

  --watch                     Watch for changes and upload automatically (default: false, env: IMMICH_WATCH_CHANGES)  

  --help                      display help for command  

```

--------------------------------

### QSV devices section from hwaccel.transcoding.yml

Source: https://docs.immich.app/features/hardware-transcoding

The `qsv` section from the `hwaccel.transcoding.yml` file, showing the device mapping required for Intel Quick Sync Video.

```yaml
devices:
  - /dev/dri:/dev/dri
```

--------------------------------

### Redis Sentinel URL JSON example

Source: https://docs.immich.app/install/environment-variables

Example JSON configuration for Redis Sentinel, to be base64-encoded and used as the REDIS_URL value. It defines three sentinel nodes and the master name.

```json
{

  "sentinels": [

    {

      "host": "redis-sentinel-node-0",

      "port": 26379

    },

    {

      "host": "redis-sentinel-node-1",

      "port": 26379

    },

    {

      "host": "redis-sentinel-node-2",

      "port": 26379

    }

  ],

  "name": "redis-sentinel"

}
```

--------------------------------

### Single Compose file with inline QSV devices

Source: https://docs.immich.app/features/hardware-transcoding

Example of inlining the QSV device mapping directly into the `immich-server` service in a single Compose file, for platforms that do not support multiple Compose files.

```yaml
immich-server:
  container_name: immich_server
  image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
  # Note the lack of an `extends` section
  devices:
    - /dev/dri:/dev/dri
  volumes:
  ...
```

--------------------------------

### Example JSON log output

Source: https://docs.immich.app/features/monitoring

Example of structured JSON log output when IMMICH_LOG_FORMAT=json is enabled. Each log entry includes level, pid, timestamp (Unix ms), message, and context fields.

```json
{"level":"log","pid":36,"timestamp":1766533331507,"message":"Initialized websocket server","context":"WebsocketRepository"}  

{"level":"warn","pid":48,"timestamp":1766533331629,"message":"Unable to open /build/www/index.html, skipping SSR.","context":"ApiService"}  

{"level":"error","pid":36,"timestamp":1766533331690,"message":"Failed to load plugin immich-core:","context":"Error"}  

```

--------------------------------

### Run Immich CLI Docker upload with parameters

Source: https://docs.immich.app/features/command-line-interface

Runs the Immich CLI in Docker with upload parameters appended directly to the command line. This example uploads with -a, -c 5, and --recursive from the directory/ path.

```bash
docker run -it -v "$(pwd)":/import:ro -e IMMICH_INSTANCE_URL=https://your-immich-instance/api -e IMMICH_API_KEY=your-api-key ghcr.io/immich-app/immich-cli:latest upload -a -c 5 --recursive directory/
```

--------------------------------

### Create and move to the Immich app directory

Source: https://docs.immich.app/install/docker-compose

Creates a directory named ./immich-app and moves into it to hold the docker-compose.yml and .env files.

```bash
mkdir ./immich-app  

cd ./immich-app  
```

--------------------------------

### Prepare Postgres database for Immich without superuser

Source: https://docs.immich.app/administration/postgres-standalone

Run at the psql prompt to prepare the database for Immich without superuser permissions. Recommended for advanced users only; manual intervention is often required when updating Immich. Automated backups still require superuser permission due to pg_dumpall.

```sql
CREATE DATABASE <immichdatabasename>;  

\c <immichdatabasename>  

BEGIN;  

ALTER DATABASE <immichdatabasename> OWNER TO <immichdbusername>;  

CREATE EXTENSION vchord CASCADE;  

CREATE EXTENSION earthdistance CASCADE;  

COMMIT;  

```

--------------------------------

### Change columns to vector types after installing VectorChord

Source: https://docs.immich.app/administration/postgres-standalone

After installing VectorChord, run these SQL commands to change the columns back to vector types. Replace <number> with the dimension size obtained in the first step of the manual migration.

```sql
CREATE EXTENSION IF NOT EXISTS vchord CASCADE;  
ALTER TABLE smart_search ALTER COLUMN embedding SET DATA TYPE vector(<number>);  
ALTER TABLE face_search ALTER COLUMN embedding SET DATA TYPE vector(512);  


```

--------------------------------

### Normal pg_amcheck output

Source: https://docs.immich.app/FAQ

Example of a normal result from the pg_amcheck command, ending with 100% relations and pages processed.

```text
7470/8832 relations (84%), 730829/734735 pages (99%)  

8425/8832 relations (95%), 734367/734735 pages (99%)  

8832/8832 relations (100%), 734735/734735 pages (100%)  


```
Tokens:
Raw