skip to content

A Flutter real-estate gallery of large remote photos crashes with out-of-memory on older phones; how does ImageCache behave, and what would you change?

level: seniorimportance: should knowfreq 40%

answer

  1. 1000 entries, 100 MiB by default
  2. live images are not counted
  3. bigger than the byte limit: not cached
  4. memory pressure clears the cache
  5. decode smaller before tuning limits

basics

~20 s

ImageCache keeps up to 1000 decoded images or 100 MiB, but images still on screen are live and not counted. Such crashes usually come from decoding full-resolution photos, so decode smaller with cacheWidth first, then tune the limits.

solid answer

~40 s

`PaintingBinding.instance.imageCache` has three parts: pending loads, an LRU cache of completed images capped by `maximumSize` (1000) and `maximumSizeBytes` (100 MiB), and **live** images, those whose stream still has listeners, such as every photo on screen. The byte limit governs only the LRU part, so twelve full-resolution photos visible at about 46 MiB each blow past any limit; an image bigger than `maximumSizeBytes` is not cached at all. On a memory-pressure signal Flutter calls `imageCache.clear()`, which also leaves live images alone. So I fix decode size first with `cacheWidth` per context, keep the gallery lazy (`GridView.builder` or `PageView.builder`), precache only neighbours, and then lower `maximumSizeBytes` in `main()` if the budget is still too high.

code

dart · 29 lines
dart
import 'package:flutter/material.dart';

class ListingPhotoStrip extends StatelessWidget {
  const ListingPhotoStrip({super.key, required this.urls});

  final List<String> urls;

  @override
  Widget build(BuildContext context) {
    final dpr = MediaQuery.devicePixelRatioOf(context);
    const width = 280.0;
    return SizedBox(
      height: 200,
      child: ListView.builder(
        scrollDirection: Axis.horizontal,
        itemCount: urls.length,
        itemBuilder: (context, index) => Padding(
          padding: const EdgeInsets.only(right: 8),
          child: Image.network(
            urls[index],
            width: width,
            fit: BoxFit.cover,
            cacheWidth: (width * dpr).round(),
          ),
        ),
      ),
    );
  }
}

go deeper

for a junior

Know that Flutter caches decoded images in memory and that big photos shown at small sizes waste a lot of it.

for a middle

Explain the default limits, the difference between cached and live images, and why decode size matters more than file size.

for a senior

Fix a gallery OOM in order: decode size, lazy building, sparse precaching, cache limits and eviction, and confirm with oversized-image highlighting and cache counters.

for a principal

Set per-device memory budgets for image-heavy features and make the server's image renditions part of that budget.

## What ImageCache actually holds Every `ImageProvider` resolves through the global cache, `PaintingBinding.instance.imageCache` (also reachable as the top-level `imageCache`). It tracks images in three states: | State | Meaning | Counted against the limits | |---|---|---| | **pending** | still loading or decoding | no | | **cached** (keep-alive) | completed, kept for reuse, least recently used first out | **yes** | | **live** | completed and still listened to, for example by an `Image` on screen | no | The limits apply to the **cached** part: - `maximumSize`, default **1000** entries; - `maximumSizeBytes`, default **100 MiB** (`100 << 20`). When either is exceeded, the least recently used entries are evicted. An image whose decoded size alone exceeds `maximumSizeBytes` is **not cached at all**, although it can still be live while displayed. ## Why the limits do not save the gallery A decoded image costs width × height × 4 bytes. A 4000 × 3000 listing photo is about 46 MiB. The limits cannot help in three common situations: 1. **Everything visible is live.** A detail page with a horizontal strip of twelve full-resolution photos holds all twelve as live images, over 500 MiB, and none of it counts toward `maximumSizeBytes`. 2. **Non-lazy lists build everything.** A `Column` or `ListView(children: ...)` of forty photos creates forty `Image` widgets, and each starts loading at once. 3. **Other holders keep images alive.** Any code that resolves a provider and keeps its listener, for example a custom precache that never removes its listener, pins the image in memory. On a platform memory-pressure signal, `PaintingBinding.handleMemoryPressure` calls `imageCache.clear()`. That drops pending and cached entries but, as the documentation says, **not live ones**, because clearing them would not free memory that widgets still hold. ## A fix, in order of impact 1. **Decode smaller.** Give every `Image.network` a `cacheWidth` computed from its on-screen width times the device pixel ratio. A 360-pixel-wide thumbnail of that photo takes about 0.4 MB instead of 46 MiB, a reduction of roughly a hundred times. 2. **Build lazily.** Use `GridView.builder`, `ListView.builder` or `PageView.builder`, so only the photos near the viewport exist, and their images stop being live when they scroll away. 3. **Precache sparingly.** Precache the next and previous photo in a viewer, not the whole listing. 4. **Right-size the cache.** If the app still keeps too much, lower the limits early in `main()`: ```dart void main() { WidgetsFlutterBinding.ensureInitialized(); PaintingBinding.instance.imageCache.maximumSizeBytes = 60 << 20; runApp(const EstateApp()); } ``` 5. **Evict what you will not revisit.** When the user leaves a listing, evict its photos with the same provider the widgets used (for a `cacheWidth` image that is the `ResizeImage`, since a bare `NetworkImage(url).evict()` targets a different key), or call `imageCache.clear()`. Evicting only removes cache entries; images still on screen stay live. 6. **Ask the server for smaller files.** Decoding smaller saves memory; downloading smaller also saves bandwidth and decode time. ## Deferred loading helps, but only while flinging Each `Image` wraps its provider in a `ScrollAwareImageProvider`, which postpones starting a load while the list scrolls at high velocity and skips it if the widget is gone by the time scrolling slows. That keeps a fast fling from starting forty downloads, but it does nothing for photos the user stops on, so it complements decode sizing rather than replacing it. ## A budget, worked through For a phone where the gallery should stay under about 150 MB of image memory: - 12 visible thumbnails at 360 × 270: about 4.7 MB live. - 1 full-screen photo at 1170 × 878: about 4 MB live. - 2 precached neighbours at the same size: about 8 MB. - the rest of the cache: capped by `maximumSizeBytes`. The same screen with undecoded 4000 × 3000 originals would need nearly 600 MB for the thumbnails alone. ## Tools for confirming it - `debugInvertOversizedImages = true` highlights images decoded much larger than displayed and logs both sizes. - `imageCache.currentSizeBytes`, `liveImageCount` and `pendingImageCount` give quick numbers in a debug overlay or log. - Heap snapshots and memory timelines for deeper leaks are a separate diagnostic workflow. ## Replacing the cache entirely A custom `WidgetsFlutterBinding` subclass can override `PaintingBinding.createImageCache()` to return an `ImageCache` subclass, for example to log evictions. That is rarely necessary; the settings above cover almost every gallery.

  • Why doesn't lowering maximumSizeBytes to 50 MiB stop a screen showing twelve full-resolution photos from crashing?
    The byte limit governs only the cache of completed, unused images. The twelve photos on screen are live, still listened to by their `Image` widgets, and live images are not counted or evicted. The fix is to decode them smaller with `cacheWidth` and to build the strip lazily.
  • What does Flutter do with the image cache when the OS reports memory pressure?
    `PaintingBinding.handleMemoryPressure` calls `imageCache.clear()`, which evicts pending and cached entries. Live images stay, because widgets still hold them, so clearing them would not free memory. Reducing what is live is up to the app.

  • maximumSizeBytes caps all image memory, including images on screen.
  • A 2 MB JPEG uses about 2 MB of memory once displayed.
  • imageCache.clear() frees the photos currently visible.
  • An image larger than maximumSizeBytes is cached anyway and evicts everything else.
  • Raising maximumSizeBytes fixes an out-of-memory crash.