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.

saying these in an interview costs you the question

  • 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.