A cross-platform desktop front-end for immich-go — configure workflows with forms, preview the exact command, and launch it in a real terminal against your Immich server.
📖 Live Documentation Website: https://shitan198u.github.io/immich-go-gui/
immich-go is powerful but flag-heavy. Immich-Go GUI gives you:
- 11 workflow tabs covering every current immich-go upload / archive / stack subcommand
- Safe defaults — API keys in the OS keyring, secrets via environment variables, masked previews
- Profiles for home vs work (or staging vs production) Immich servers
- Pre-flight checks so you discover connection problems before a long job starts
- Automatic immich-go downloads with SHA256 verification
New here? Start with docs/ — especially Choose Your Workflow and Getting Started.
| Area | Highlights |
|---|---|
| Workflows | Upload & archive from folder, Google Photos, iCloud, Picasa, Immich; plus Stack |
| Config | Multi-profile settings, themes (system/light/dark), preferred terminal |
| Safety | Keyring secrets, env delivery, SSL warnings, process locks, dry-run |
| CLI parity | Simple mode for common fields; advanced mode for full flag surface |
| Ops | Binary manager, connection test, command preview, drag-and-drop paths |
| Platforms | Windows installer/portable, macOS DMG, Linux AppImage/DEB/RPM/tarball |
flowchart LR
classDef userStyle fill:#6366f1,stroke:#4338ca,color:#fff,stroke-width:2px
classDef guiStyle fill:#0ea5e9,stroke:#0369a1,color:#fff,stroke-width:2px
classDef cliStyle fill:#8b5cf6,stroke:#6d28d9,color:#fff,stroke-width:2px
classDef serverStyle fill:#10b981,stroke:#047857,color:#fff,stroke-width:2px
User([👤 You]):::userStyle
GUI[🖥️ Immich-Go GUI]:::guiStyle
CLI[⚙️ immich-go CLI]:::cliStyle
Server[(☁️ Immich Server)]:::serverStyle
User -->|configure & launch| GUI
GUI -->|argv + env secrets| CLI
CLI -->|upload / archive / stack| Server
⬇️ Download the latest release →
Pre-built desktop apps are available for all platforms — no Python or dependencies required:
| Platform | Package |
|---|---|
| 🪟 Windows | Immich-Go-GUI-{VERSION}-Windows-x86_64-Setup.exe (or Portable .zip) |
| 🍎 macOS | Immich-Go-GUI-{VERSION}-macOS-x86_64.dmg |
| 🐧 Linux | Immich-Go-GUI-{VERSION}-Linux-x86_64.AppImage · .deb · .rpm · .tar.gz |
Windows antivirus note: Defender or VirusTotal may flag the unsigned Nuitka build (
Trojan:Win32/Wacatac.B!ml). This is a common false positive. Always download from official GitHub Releases.
See Platform Notes for Gatekeeper, AppImage chmod +x, and other OS-specific tips.
For contributors or users who prefer source:
Prerequisites: Python 3.13 and uv.
git clone https://github.com/shitan198u/immich-go-gui.git
cd immich-go-gui
uv sync --dev
uv run app.pyOn first use, the Config tab can download a compatible immich-go binary for you.
🌐 Live Documentation Website: https://shitan198u.github.io/immich-go-gui/
Full guides live under docs/:
| Audience | Start here |
|---|---|
| Users | Getting Started · Choose Your Workflow · FAQ |
| Operators | Configuration · Security · Troubleshooting |
| Developers | Architecture · Testing · CONTRIBUTING |
| Reference | CLI mapping · Config schema · Env vars |
Version history: CHANGELOG.md.
This GUI targets immich-go 0.32.0 (tested). CLI behavior, edge cases, and flag semantics are defined upstream:
https://github.com/simulot/immich-go/
Compatibility policy: docs/reference/immich-go-compatibility.md.
Contributions are welcome. Please:
- Read CONTRIBUTING.md
- Skim the Developer Guide
- Open PRs against
master - Prefer Conventional Commits (
feat:,fix:,docs:, …) so Release Please can version cleanly
uv sync --dev
uv run pytestIf Immich-Go GUI saves you time, you can support development:
This project is licensed under the MIT License.