Immich Compatibility

Gumnut’s Immich compatibility layer supports most of the core Immich functionality. This page covers what’s supported, what isn’t, and how Gumnut differs from the official Immich server.

​

Supported Immich Version

The compatibility layer currently targets the Immich v3.2.0 API. It is v3-only rather than a dual-version adapter, so use a current Immich v3 app when connecting to Gumnut.

​

Library Selection

Immich does not expose a library selector. The Library setting appears in Settings > Immich in the Gumnut app when you own at least two libraries, collaborate on a library, or have a saved choice. If you own just one library, collaborate on none, and have no saved choice, the setting is hidden. When the setting appears, you can select Default, a library you own, or a library where you are a collaborator. The choice is account-level and shared by your Immich clients except those using an API key limited to selected libraries. Those clients do not use the setting; the key’s selected libraries control access, and requests without an explicit library can fail. The setting does not grant access beyond your membership or API-key scope. For clients that use the setting, Default uses the oldest live library that you own — the one you own that was created earliest. A selected library must be live and must give you the owner or collaborator role; a viewer library cannot be selected for Immich. If the selected library becomes unavailable, the compatibility layer falls back to the oldest live library you own. It uses the resolved library for browsing, search, albums, people, faces, stacks, uploads, and sync, so one Immich connection does not mix records from different Gumnut libraries. If your account has access only to shared libraries and has no usable selection, clients that can list libraries receive 403 instead of selecting a library you can only view. You need an owned library or collaborator access to use Immich with that account. Immich’s library-management endpoints are compatibility stubs rather than a way to manage Gumnut libraries. Use the Gumnut app to choose the library for Immich, and use the REST API to manage library content and membership. Changing the library may take a few minutes to reach an existing Immich session. When the session switches libraries — including after the selected library becomes unavailable — Immich resets sync and resynchronizes from the new library. If the library in use is trashed, a request can fail before the session switches to its fallback library.

​

Supported Features

These Immich features work with Gumnut:

​

Not Yet Supported

These Immich features are not currently available through Gumnut. Some may be added in the future: The map view works for assets that already have GPS coordinates, including maps opened from an album. Immich’s Explore view can show Places grouped by city when your assets include location data. Recent photos appears independently. You can change an asset’s location by dropping a pin on the map; the place-name box in that dialog returns no results.

​

Edited assets and downloads

Gumnut keeps the original upload when an editing tool creates a new current rendering. Immich shows an asset as edited whenever its current rendering is not the original upload, including in asset views, mobile sync, and real-time updates. For an individual full-quality download, use the edited selector on GET /api/assets/{id}/original:

• edited=false (the default) returns the exact bytes from the original upload.
• edited=true returns the current rendering.

For an asset that has never been edited, both choices return the same file. Downloads support range requests, so an Immich client can resume an interrupted transfer. If the original upload is unavailable or the asset’s version history is inconsistent, the adapter returns an error rather than silently substituting another rendering. Bulk ZIP downloads also honor edited: the default (false or omitted) selects each asset’s original upload, while edited=true selects each asset’s current rendering. The download-info response reports original-upload sizes, matching the default archive selection. Face boxes use the original upload’s pixel coordinates. While an edited rendering is current, Gumnut suppresses face geometry so those boxes are not drawn over the wrong pixels: face reads return no geometry, attempts to add a face box return a conflict, and synced face rows are hidden or retracted. Restoring the original rendering makes the geometry available again; checkpointed clients converge after a subsequent face event or a full resync.

​

Stacks

Gumnut supports the core Immich stack workflows:

• When the Immich client requests timeline data with withStacked, each burst stack is represented by one frame and its badge shows the number of live frames. Requests without withStacked continue to return every frame.
• The time-bucket count still includes every frame, even when the bucket contents are collapsed into stacks.
• You can open a stack from the timeline and browse its live members. Asset details include a stack summary when the asset belongs to a stack with at least two live members.
• You can dissolve a stack or remove an individual asset from it. These actions change only the grouping; the photos remain in your library. If removal leaves fewer than two live members, the stack is dissolved and its cover is cleared as needed.
• Stacks with no live members are omitted from stack searches and return not found when opened directly.
• If stack resolution fails while a timeline loads, Gumnut leaves that burst uncollapsed instead of hiding its frames.
• Mobile sync sends stack changes incrementally, and synced assets retain their stack membership. When a stack is dissolved, member updates arrive before the stack is removed so the client can keep the library consistent.
• If a stack referenced by a sync is absent from the bulk read, Gumnut checks it directly. A stack that was deleted before its update reached the sync is treated as deleted, so it does not wedge the sync; a stack that is still present but temporarily missing is retried instead of being acknowledged. This prevents a transiently missing stack from hiding its burst in the mobile timeline.
• If a stack still cannot be resolved after that check, Gumnut leaves its assets ungrouped rather than dropping them. The incomplete sync is not acknowledged, so the client can retry it.

​

Favorites and ratings

You can use Immich’s favorite and rating controls with Gumnut. Favorites and ratings share one scale: marking an asset as a favorite uses rating 5, while clearing the favorite uses rating 0 (unrated). You can also assign an exact rating from 1 through 5. Immich asset responses expose favorites as isFavorite and ratings as exifInfo.rating. Unrated assets return a null rating. You can filter supported asset lists and search endpoints by favorite or rating. Timeline results and global map results also support the favorite filter: If you send both filters, rating takes precedence over isFavorite. Single-asset changes are sent to connected clients through real-time updates. Bulk changes appear after the next refresh or sync.

​

Intentionally Different

Some features work differently in Gumnut by design:

• Favorites and ratings share one scale — Immich’s favorite heart maps to a rating of 5 in Gumnut. Favoriting a photo sets its rating to 5, unfavoriting clears it to 0, and choosing another rating updates that same value.
• Camera and place search ranks rather than filters — Immich presents camera make, model, and lens, and city, state, and country as filters. Gumnut matches them as search terms instead, so results are ordered by how well they match rather than restricted to exact matches: searching for Canon surfaces your Canon photos first but can include others. Combining one of these terms with your own search text can also dilute that text, since the terms are matched alongside it rather than narrowing it. Exact filtering isn’t available yet.
• No external libraries — Immich allows importing photos from external file paths on the server. Gumnut does not support this because it runs as a managed cloud service, not on your local machine. You always have full access to your original assets and metadata through the API.
• No admin-level ML configuration — Immich lets you customize embedding models, ML processing settings, and other server-level options. Gumnut manages these automatically — you get the latest models and optimizations without configuration.
• Automatic face grouping into people — Gumnut uses a more sophisticated recognition pipeline than Immich’s per-face matching, with crowd-face filtering, library-wide re-clustering, and sibling-aware matching. See Faces and People for details.
• CDN delivery instead of home-server serving — A self-hosted Immich server serves photos directly from your home machine and network, which is limited by your home upload bandwidth and requires exposing the server to the internet. Gumnut delivers your photos through Cloudflare’s global CDN backed by cloud storage, so they load quickly from anywhere without those constraints.
• No server administration — Immich exposes admin endpoints for managing users, jobs, and system settings. Gumnut handles infrastructure and administration automatically.
• API keys are managed in Gumnut, not Immich — Immich’s API Keys settings page doesn’t create working keys. Create and revoke keys in the Gumnut dashboard instead; see API Keys.

​

Gumnut vs Official Immich Server