Skip to content

fix(immich): prevent OOM crash on large images and fix video asset handling#625

Open
iAndrea wants to merge 2 commits into
fatihak:mainfrom
iAndrea:immich-album-optimizations
Open

fix(immich): prevent OOM crash on large images and fix video asset handling#625
iAndrea wants to merge 2 commits into
fatihak:mainfrom
iAndrea:immich-album-optimizations

Conversation

@iAndrea
Copy link
Copy Markdown
Contributor

@iAndrea iAndrea commented Mar 16, 2026

Problem

The Immich plugin was downloading full-resolution originals (up to 24MB+) on
every refresh, causing OOM kills on low-RAM devices (e.g. Pi Zero). Additionally,
video assets in albums could be selected and passed to Image.open(), causing
a crash, and a missing import requests caused a NameError that swallowed
the real error in the image loader.

Changes

image_album.py

  • Download preview instead of original — replace the hard-coded
    /api/assets/{id}/original URL with a version-aware resolver that probes
    the server once (streaming GET, no body downloaded) and caches the working
    endpoint for the lifetime of the provider:
    1. /api/assets/{id}/thumbnail?size=preview — current Immich API
    2. /api/assets/{id}/thumbnail — older versions without size param
    3. Falls back to /original with a warning if both fail
  • Switch asset fetch to album endpoint — replace the paginated
    POST /api/search/metadata loop with a single GET /api/albums/{id},
    with client-side type == "IMAGE" filtering to exclude video assets
  • README — add asset.view to the required API key permissions

image_loader.py

  • Fix NameError in exception handlersrequests was referenced in
    except requests.exceptions.RequestException but never imported
  • Eliminate redundant memory copy in _load_from_url_fast — replace
    BytesIO(response.content) (two copies of compressed bytes in memory) with
    response.raw piped directly into PIL; decode_content=True handles
    gzip/deflate transparently

Required API key permissions

asset.view (NEW), asset.read, asset.download, album.read

@wildmor
Copy link
Copy Markdown

wildmor commented Apr 29, 2026

I can confirm this PR fixes the OOM issue on Raspberry Pi Zero 2 W.
My setup: RPi Zero 2 W (512MB RAM) + InkyPi + Image Album plugin pulling photos from Immich. The album contains a mix of Android and iPhone (HEIC) photos.
Before this fix, InkyPi was regularly killed by earlyoom — Python was spiking to ~126MB RAM during image processing, which on a 512MB device left no headroom for anything else. HEIC photos from iPhone were particularly painful since they were served as full-resolution originals.
After applying this PR, no OOM kills since. Great fix, hope it gets merged soon!

Copilot AI added a commit to BaloMueller/UDash that referenced this pull request May 4, 2026
# Conflicts:
#	src/plugins/image_album/image_album.py

Co-authored-by: BaloMueller <793558+BaloMueller@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants