Skip to content

Desktop GUI · Open Source · Cross-platform

Immich-Go GUI

A beautiful desktop GUI for immich-go — bulk upload, archive, and stack your media with Immich.

Get Started Choose Your Workflow Downloads

Windows · macOS · Linux

Immich-Go GUI is a cross-platform desktop application (PySide6/Qt) that wraps the immich-go CLI. Configure jobs with forms, preview the exact command, and launch bulk media operations against your Immich server — without memorizing a forest of flags.

Why Immich-Go GUI?

Full workflow coverage

Eleven tabs for every upload, archive, and stack path — folder, Google Photos, iCloud, Picasa, Immich-to-Immich, and more.

Secrets done right

API keys live in the OS keyring, travel as environment variables, and stay masked in previews and logs.

Multi-server profiles

Home vs work, staging vs production — switch Immich targets without re-entering credentials each time.

Pre-flight safety

Connection tests, dry-run, process locks, and SHA256-verified binary downloads before long jobs start.

Simple & advanced modes

Friendly defaults for common fields, with a full flag surface when you need power-user control.

Real terminal launches

Jobs open in your preferred terminal so progress, errors, and resumes stay visible and inspectable.

See it in action

Immich-Go GUI Demonstration

Start here

Pick the path that matches what you need right now.

First run Getting Started Install binaries or run from source, then take the first-run tour. Decision help Choose Your Workflow Decision tree and recipes for folder, cloud takeouts, and server-to-server. Stuck? Troubleshooting Locks, terminals, SSL, antivirus, and 403s — fix it fast. Trust Security & Privacy Keyring, env secrets, SSL, and the threat model explained clearly. Contributors Architecture UI vs core split, data flow, and how to extend the app safely. Lookup CLI Command Mapping Every GUI tab mapped to immich-go subcommands and flags.

System architecture

flowchart TB
    classDef userStyle fill:#6366f1,stroke:#4338ca,color:#fff,stroke-width:2px
    classDef coreStyle fill:#8b5cf6,stroke:#6d28d9,color:#fff,stroke-width:2px
    classDef runStyle fill:#f59e0b,stroke:#b45309,color:#fff,stroke-width:2px
    classDef extStyle fill:#10b981,stroke:#047857,color:#fff,stroke-width:2px

    User([User]):::userStyle

    subgraph GUILayer["Immich-Go GUI"]
        direction TB
        Config[Config Manager]:::coreStyle
        Builder[Command Builder]:::coreStyle
        Validator[Input Validator]:::coreStyle
        BinMgr[Binary Manager]:::coreStyle
        Process[Process Runner]:::runStyle
    end

    subgraph External["External"]
        direction TB
        Binary[immich-go CLI]:::extStyle
        Server[(Immich Server)]:::extStyle
    end

    User -->|configure| Config
    User -->|fill form| Builder
    Builder --> Validator
    Validator --> Process
    Builder --> Process
    Config --> Process
    BinMgr --> Binary
    Process -->|launch with argv + secrets| Binary
    Binary -->|upload / archive / stack| Server

Suggested reading order

New users

  1. Getting Started — install and first launch
  2. Platform Notes — OS-specific paths and quirks
  3. Configuration — server, keys, binary, themes
  4. Choose Your Workflow — pick the right tab
  5. Your workflow page — Upload / Archive / Stack
  6. Troubleshooting & FAQ — keep bookmarked

Contributors

  1. Architecture
  2. Core Modules
  3. Testing
  4. Adding Tabs and Flags
  5. CI/CD and Releases

Documentation map

User Guide

Setup Getting Started Install binaries or run from source; first-run tour. OS Platform Notes Windows / macOS / Linux install quirks and paths. Recipes Choose Your Workflow Decision tree and common library recipes. Settings Configuration Server, API keys, binary manager, themes, admin key. Multi-env Profiles Multi-server and multi-environment setups. Import Upload Workflows Folder, Google Photos, iCloud, Picasa, Immich-to-Immich. Export Archive Workflows Local export tabs plus Archive from Immich. Server Stack Burst / RAW / HEIC stacking on the Immich server. Power user Advanced Flags Simple vs advanced mode; per-tab flag reference. Safety Security & Privacy Keyring, env secrets, SSL, threat model. Support Troubleshooting Locks, terminals, SSL, antivirus, 403s. Q&A FAQ Short answers to the most common questions. Terms Glossary Shared vocabulary for the project and Immich.

Developer Guide

Overview Architecture UI vs core split, data flow, security model. Code Core Modules Module-by-module core/ reference. Extend Adding Tabs & Flags Grow CLI parity without breaking safety. Quality Testing pytest, fixtures, headless Qt, _norm_argv. Ship CI/CD & Releases Branching, Release Please, packaging. Tooling Scripts CLI help capture and review utilities.

Reference

Config Config Schema TOML fields, OS paths, and overrides. Env Environment Variables IMMICH_GO_* secret and server env map. CLI CLI Command Mapping Maps all 11 GUI tabs to immich-go subcommands. Versions immich-go Compatibility Tested versions, download, SHA256 checks.
File Purpose
README Project landing page
CONTRIBUTING How to contribute
CHANGELOG Version history
LICENSE MIT license
Version note: Docs track the application as of v1.4.2, tested with immich-go 0.32.0. If something in the UI disagrees with a page, prefer the running app and open an issue or PR.