How Flutter’s Image.network Loads and Caches Images – A Deep Source‑Code Dive

Overview

The Flutter Image widget is a StatefulWidget that displays pictures, similar to Android’s ImageView. While using Image.network looks like a one‑liner, a complex chain of classes and methods works behind the scenes to fetch, decode, cache, and render the image.

Image Constructors

Flutter provides several factory constructors for Image (e.g., Image.asset, Image.network, Image.file). The Image.network constructor simply stores a NetworkImage (an ImageProvider) and forwards all visual parameters such as width, height, fit, colorBlendMode, etc.

ImageState Lifecycle

When an Image widget is inserted into the tree, its associated _ImageState is created. The state does not override initState but implements didChangeDependencies. In this method the state calls _resolveImage() to start the loading process and then either _listenToStream() or _stopListeningToStream() depending on the current TickerMode.

Resolving an Image

_resolveImage()

builds a new ImageStream by invoking widget.image.resolve(). The resolve method lives in the abstract ImageProvider class and creates an ImageStream that is linked to an ImageStreamCompleter. If a cached completer exists for the same key, it is reused; otherwise the provider’s load method is called to create a new completer.

NetworkImage Loading

NetworkImage

overrides load and returns a MultiFrameImageStreamCompleter. The completer receives a Future<ui.Codec> from the private _loadAsync method, which performs an HTTP GET request, validates the response, reads the bytes, and finally calls ui.instantiateImageCodec to obtain a codec capable of decoding static or animated images.

Future<ui.Codec> _loadAsync(NetworkImage key) async {

After the codec is ready, the completer schedules frame extraction. For a single‑frame image the codec’s getNextFrame() is called once, an ImageInfo is created, and _emitFrame forwards it to listeners. For animated images the completer repeatedly extracts frames and schedules them via SchedulerBinding.instance.scheduleFrameCallback.

Caching Mechanism

The global PaintingBinding.instance.imageCache stores up to 1000 images or 10 MiB by default. When resolve is called, the cache’s putIfAbsent method checks for an existing ImageStreamCompleter. If none exists, the newly created completer is inserted and the image size is accounted for. Eviction follows a least‑recently‑used policy.

ImageStream and Listeners

The ImageStream holds a list of ImageListener callbacks. _listenToStream() adds _handleImageChanged as a listener, which updates the widget’s state with the latest ImageInfo. The build method then returns a RawImage widget that renders the decoded ui.Image using the stored visual parameters. Widget build(BuildContext context) { When the image changes, setState triggers a rebuild, and RawImage displays the picture with the appropriate width, height, fit, alignment, etc.

Key Takeaways

The Image widget delegates image fetching to an ImageProvider (e.g., NetworkImage).

Resolution creates an ImageStream linked to a completer that handles decoding and caching.

Flutter’s default cache is memory‑based; developers can replace or extend it for disk caching.

Animated images are processed by MultiFrameImageStreamCompleter, which schedules frame callbacks.