Mimick is an unofficial Immich desktop client for Linux. It provides a GTK4/libadwaita interface for automatic background sync of local photo and video folders to a self-hosted Immich server, and an optional library browser for viewing, searching, and managing assets directly from the desktop.
This is a community-developed project and is not affiliated with or endorsed by the Immich project.
Status: Supports Immich v1.118+.
| Library View (Light) | Explore View |
|---|---|
 |
 |
| Sync Status Dashboard | Settings & Watch Folders |
 |
 |
- Asynchronous Concurrent Uploads: Configurable parallel worker tasks (1–10 streams) stream files from disk, maintaining flat memory usage footprints.
- SHA-1 Deduplication: Verifies files locally via checksum prior to upload, utilizing payload logic identical to official Immich mobile apps.
- Atomic File Monitoring: Delays queuing until file sizes stabilize and physical write locks are released, preventing partial data uploads.
- One-Way Mirroring: Maintains strictly read-only access to local system files.
- Persistent Offline Storage: Upload network failures are safely serialized to disk (
~/.cache/mimick/retries.json) and gracefully replayed during subsequent daemon lifecycles. - Local State Indexing: Unmodified, previously uploaded media is aggressively skipped during startup catch-up scans using local indexes to minimize disk I/O overhead.
- Queue Inspector: Interactive UI module to interpret active error payloads, selectively retry specific dropped files, or flush the active failure queue.
- Dynamic Endpoint Resolution: Automatically negotiates requests between configured Internal (LAN) and External (WAN) URI addresses based on immediate network topologies and heartbeat reachability.
- Native Implementation: Developed purely in Rust, utilizing GTK4 and Libadwaita bindings alongside an AppIndicator system tray for headless daemon control.
- Hardware Awareness: Integrates with
nmcliand/sys/class/power_supplyto identify running states and optionally defer daemon I/O operations strictly during explicitly metered networks or active battery deployments. - Sandbox Security: Employs Flatpak desktop portal file-choosers to grant the application isolated, per-directory access without requesting system-wide filesystem permissons.
- Encrypted Keystore: API keys are stored securely via the oo7 keyring library. Inside Flatpak, credentials are kept in a portal-encrypted file within the sandbox. On native installs, the desktop's Secret Service (GNOME Keyring, KWallet) is used.
- Quiet Hours: Configurable chronological barriers to globally suspend daemon uploads.
Each watched directory operates with isolated logical constraints:
- Static or dynamically generated Immich album targets.
- Pre-flight omission of hidden paths (dotfiles).
- Predetermined allowance lists strictly for explicit file extensions (e.g.
.avif,.mp4). - Upper-bound maximum file size ceilings.
- Built-in album browser with thumbnail grid and Explore landing page.
- Search modes: filename/metadata, Smart (CLIP), and OCR text lookup.
- Download originals and open full-resolution previews in the lightbox.
- Toggle via Settings → Behavior → Enable Library View (restart required).
The easiest and official way to install Mimick on any Linux distribution is via Flathub. This ensures you receive automatic updates whenever a new version is released.
Prerequisites: Flatpak must be installed on your system.
You can install Mimick directly from Flathub:
flatpak install flathub dev.nicx.mimick(Note: If you haven't setup Flathub yet, follow the setup guide for your distribution at flathub.org/setup.)
Launch Mimick from your Application Launcher. The settings window opens automatically on first launch.
The window is split into two pages:
- Settings for server details, behavior switches, watch folders, and folder rules
- Status for sync health, queue actions, manual sync, pause/resume, and diagnostics export
The UI is fully responsive and automatically adapts its layout for narrow widths (sub-360px), making it compatible with mobile Linux devices.
- Internal URL — LAN address (e.g.,
http://192.168.1.50:2283). - External URL — WAN/Public address (e.g.,
https://photos.example.com). At least one must be enabled. - API Key — Generate in Immich Web UI under Account Settings > API Keys. See Required API Key permissions below for the minimum scopes and which features unlock with each.
- Watch Paths — Add folders to monitor with the built-in folder picker. Each folder can be assigned a target Immich album.
- Run on Startup — Enable this in the Behavior section to start Mimick automatically when you log in.
- Folder Rules — Each watched folder can open a rules dialog to ignore hidden paths, set a max size in MB, or restrict uploads to specific extensions.
- Sync Controls — Use Pause, Resume, or Sync Now from the settings window or tray menu when you want manual control.
- Queue Inspector — Review recent queue events, inspect failed uploads, retry individual files, retry all failures, or clear the failed queue.
- Export Diagnostics — Create a support bundle from the settings window when troubleshooting sync issues.
- Save Changes — Applies your settings immediately without relaunching Mimick.
- Close / Quit —
Closehides the settings window and leaves Mimick running;Quitfully exits the app.
The bottom footer keeps Close, Quit, and Save Changes visible even when the page content needs scrolling.
When generating the API key in Immich (Account Settings → API Keys), grant only what you need:
Base — required for any sync to work:
| Permission | Why |
|---|---|
asset.upload |
Send media to the server |
asset.update |
Apply correct timezone metadata after upload |
album.read |
Look up the target album for a watch folder |
album.create |
Auto-create the target album if it doesn't exist |
album.addAsset |
Link uploaded media to the target album |
Optional — only required for the features you enable:
| Feature | Additional permissions |
|---|---|
| Library / Explore view (browse photos inside Mimick) | asset.read, asset.view, asset.download, person.read |
| Sync Method set to Full or Download Only (folder rules) | asset.read, asset.download |
| Mirror Folder Deletions to Album (folder rules toggle) | asset.delete and album.removeAsset (the latter is used when the same asset is referenced by another watch folder, so we just unlink instead of trashing) |
| Mirror Album Deletions to Folder (folder rules toggle) | No additional remote permissions — the album listing is already covered by album.read, the trash happens locally |
If you grant all, every feature works without further configuration. The granular list above is for users who prefer least-privilege keys.
Use the built-in Run on Startup switch in the settings window.
- Flatpak builds request background/autostart permission through the desktop portal.
- Native builds write an autostart desktop entry to
~/.config/autostart/dev.nicx.mimick.desktop.
Mimick now uses selected-folder access instead of full home-directory access in Flatpak.
- Add watch folders from the settings window so the file chooser portal can grant access.
- If you are upgrading from an older build that had full home access, re-add your existing watch folders once so the new permission model can take effect.
- Portal-backed folders may appear by name in the UI and logs instead of showing the raw
/run/user/.../doc/...sandbox path.
Mimick can process existing files and adapt to configuration changes automatically.
- On startup (or when clicking Sync Now), Mimick rescans watched folders to queue missing media. You can constrain this with the Startup Catch-up Mode (e.g., "Recent Changed Only" or "New Files Only") to save disk I/O.
- A local sync index (stored safely in the persistent data directory) ensures unchanged files that are already synced are skipped efficiently. Clearing the application cache will not wipe your sync state.
- If you change a watch folder's target album, unchanged files are automatically reassociated to the new album on the next scan without requiring a full reupload.
- If a previously targeted album is deleted, Mimick refreshes album resolution and recreates or rebinds the target album as needed.
- For deeper manual synchronization, the Library View provides on-demand, bidirectional album syncing to download or upload differences between linked folders and remote albums.
Mimick is a background app, so closing the settings window does not quit it.
- Use Close in the settings window or the window close button to hide the window and keep Mimick running in the tray.
- Use Quit from the tray menu, the settings window, or the launcher action to stop the app completely.
Mimick now includes a small control center for active troubleshooting and recovery.
On the Status page:
- Sync Now reruns the watched-folder scan immediately.
- Pause toggles upload activity without quitting Mimick.
- Queue Inspector shows failed items and recent queue activity from the current session.
- Retry All Failed requeues everything currently stored in the failed list.
- Retry on a single failed row requeues only that item.
- Clear Failed Queue removes persisted failed items you no longer want Mimick to retry.
- Export Diagnostics writes a bundle with
summary.txt,config.redacted.json,status.redacted.json,retries.redacted.json,synced_index.redacted.json, andprivacy-note.txt.
If enabled in the Behavior section, Mimick can pause uploads automatically:
- on metered connections, detected best-effort via
nmcli - while running on battery power, detected best-effort from
/sys/class/power_supply
These options defer uploads rather than changing your watch configuration, so syncing resumes when conditions improve or when you manually resume.
If you prefer to compile Mimick yourself, you can build it natively or package it as a local Flatpak.
- Rust toolchain (
cargo): https://rustup.rs - GTK4 + Libadwaita development headers
Ubuntu / Debian:
sudo apt install libgtk-4-dev libadwaita-1-dev libglib2.0-dev pkg-config build-essential
Fedora:
sudo dnf install gtk4-devel libadwaita-devel pkg-config
Arch Linux:
sudo pacman -S gtk4 libadwaita pkgconf base-devel
git clone https://github.com/nicx17/mimick.git
cd mimick
cargo build --release
# Copy the desktop file and icons from setup/ to ~/.local/share/applications and ~/.local/share/icons for launcher integration
# Run Directly
cargo run # start in background mode
cargo run -- --settings # open the settings window immediately
Logs written to the terminal and to ~/.cache/mimick/mimick.log include timestamps.
Terminal logs are colorized by level, and file logs rotate automatically.
-
Logging: Mimick now uses a colored console formatter for human-friendly terminal output and a plain file formatter for persistent logs. File logs are rotated automatically (approx. 2 MB per file; 5 files kept). Control verbosity with
RUST_LOG(for example:RUST_LOG=debug). See wiki/Development.md for details on the logger configuration. -
Notifications: To reduce notification spam, Mimick aggregates multiple worker uploads into a single batch summary notification when a sync cycle completes. A separate "Connection Lost" notification is still emitted for connectivity failure events.
- Most settings (worker count, quiet hours, folder rules, per-folder album, watch-folder additions/removals) are applied live when changed in the Settings window.
- Connectivity edits (API key and server URLs) are intentionally save-only and require clicking Save within the Connectivity group to take effect. This reduces accidental partial-configuration of server credentials during exploratory edits.
git clone https://github.com/nicx17/mimick.git
cd mimick
flatpak-builder --user --install --force-clean build-dir dev.nicx.mimick.local.yml
flatpak run dev.nicx.mimick
Mimick currently publishes a few concrete trust signals:
- GitHub release assets with checksums
- CodeQL analysis in GitHub Actions
- CI checks for formatting, linting, tests, and dependency audits
Pull requests are welcome. See CONTRIBUTING.md for commit and style guidelines.
- Application icon illustration by Round Icons on Unsplash.
GNU General Public License v3.0 — see LICENSE.