Use a library that loads images asynchronously

Oct 13, 2025 by wbrum.org 131 views

Impeller Loading a Large Resolution Image will Block the Main Thread and Cause Animation to Freeze

Loading a large resolution image in Flutter can cause the main thread to be blocked, resulting in animation freezing. This issue can be particularly problematic when working with high-resolution images, as it can lead to a poor user experience.

Steps to Reproduce

To reproduce this issue, follow these steps:

Load a sample page that includes a large resolution image.
Observe the animation or UI behavior of the page.
Note that the animation or UI behavior is frozen or not responding.

Code Sample

The following code sample demonstrates how to load a large resolution image in Flutter:

import 'dart:ui' as ui;
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

class SecondPage extends StatefulWidget {
  const SecondPage({Key? key}) : super(key: key);

  @override
  _SecondPageState createState() => _SecondPageState();
}

class _SecondPageState extends State<SecondPage> {
  String message = 'initializing...';

  @override
  void initState() {
    super.initState();
    print(" image_bench initstate");
    _test();
  }

  void _test() async {
    print(" image_bench test");
    _loadAssetImage("assets/images/example123.jpg");
    _loadAssetImage("assets/images/example123.jpg");
  }

  static ByteData? _data;

  static Future<ui.Image> _loadAssetImage(String assetPath) async {
    _data ??= await rootBundle.load(assetPath);
    print("image_bench _loadAssetImage");
    Uint8List bytes = Uint8List.view(_data!.buffer);
    ui.Image image = await decodeImageFromList(bytes);
    return image;
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('The Second Page'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(message),
            ElevatedButton(
              onPressed: () {
                Navigator.pop(context);
              },
              child: const Text('Back to the main page'),
            ),
          ],
        ),
      ),
    );
  }
}

What Target Platforms are You Seeing this Bug on?

This issue is observed on Android devices.

OS/Browser Name and Version | Device Information

Xiaomi 14 Pro
HyperOS 2.0
Android V
Qualcomm SM8650-AB Snapdragon 8 Gen 3 (4 nm)
Octa-core (1x3.3 GHz Cortex-X4 & 3x3.2 GHz Cortex-A720 & 2x3.0 GHz Cortex-A720 & 2x2.3 GHz Cortex-A520)
Adreno 750

Does the Problem Occur on Emulator/Simulator as Well as on Physical Devices?

Unknown

Logs

[Paste your logs here]

Flutter Doctor Output

[!] Flutter (Channel [user-branch], 3.29.0, on Ubuntu 24.04.2 LTS
    6.11.0-19-generic, locale zh_CN.UTF-8) [187ms]
    ! Flutter version 3.29.0 on channel [user-branch] at
      /home/mi/workspace/devkit/flutter
      Currently on an unknown channel. Run `flutter channel` to switch to an
      official channel.
      If that doesn't fix the issue, reinstall Flutter by following instructions
      at https://flutter.dev/setup.
    ! Upstream repository unknown source is not a standard remote.
      Set environment variable "FLUTTER_GIT_URL" to unknown source to dismiss
      this error.
    • Framework revision 35c388afb5 (4 周前), 2025-02-10 12:48:41 -0800
    • Engine revision 010c8a806b
    • Dart version 3.7.0 (build 3.7.0-323.0.dev)
    • DevTools version 2.42.0
    • If those were intentional, you can disregard the above warnings; however
      it is recommended to use "git" directly to perform update checks and
      upgrades.

[✓] Android toolchain - develop for Android devices (Android SDK version 35.0.0)
    [5.2s]
    • Android SDK at /home/mi/Android/Sdk
    • Platform android-35, build-tools 35.0.0
    • ANDROID_HOME = /home/mi/Android/Sdk
    • Java binary at:
      /home/mi/.local/share/JetBrains/Toolbox/apps/android-studio/jbr/bin/java
      This is the JDK bundled with the latest Android Studio installation on
      this machine.
      To manually set the JDK path, use: `flutter config
      --jdk-dir="path/to/jdk"`.
    • Java version OpenJDK Runtime Environment (build
      17.0.11+0-17.0.11b1207.24-11852314)
    • All Android licenses accepted.

[✓] Chrome - develop for the web [100ms]
    • Chrome at google-chrome

[✗] Linux toolchain - develop for Linux desktop [364ms]
    • Ubuntu clang version 18.1.3 (1ubuntu1)
    • cmake version 3.31.6
    ✗ ninja is required for Linux development.
      It is likely available from your distribution (e.g.: apt install
      ninja-build), or can be downloaded from
      https://github.com/ninja-build/ninja/releases
    • pkg-config version 1.8.1
    ✗ GTK 3.0 development libraries are required for Linux development.
      They are likely available from your distribution (e.g.: apt install
      libgtk-3-dev)

[✓] Android Studio (version 2024.2) [97ms]
    • Android Studio at
      /home/mi/.local/share/JetBrains/Toolbox/apps/android-studio
    • Flutter plugin version 81.1.3
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build
      17.0.11+0-17.0.11b1207.24-11852314)

[✓] IntelliJ IDEA Ultimate Edition (version 2024.3) [15ms]
    • IntelliJ at
      /home/mi/.local/share/JetBrains/Toolbox/apps/intellij-idea-ultimate
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart

[✓] VS Code (version 1.98.1) [15ms]
    • VS Code at /usr/share/code
    • Flutter extension version 3.106.0

[!] Proxy Configuration [49ms]
    • HTTP_PROXY is set
    • NO_PROXY is localhost,127.0.0.0/8,::1
    • NO_PROXY contains localhost
    ! NO_PROXY does not contain 127.0.0.1
    • NO_PROXY contains ::1

[✓] Connected device (3 available) [332ms]
    • 23116PN5BC (mobile) • e4c83c3f • android-arm64  • Android 15 (API 35)
    • Linux (desktop)     • linux    • linux-x64      • Ubuntu 24.04.2 LTS
      6.11.0-19-generic
    • Chrome (web)        • chrome   • web-javascript • Google Chrome
      134.0.6998.88

[✓] Network resources [1,968ms]
    • All expected network resources are available.

Solution

To solve this issue, you can use the following approaches:

Use a library that loads images asynchronously: You can use a library like cached_network_image or flutter_cache_manager to load images asynchronously. These libraries provide a way to load images in the background, which can help prevent the main thread from being blocked.
Use a widget that can handle large images: You can use a widget like Image.memory or Image.file to display large images. These widgets are designed to handle large images and can help prevent the main thread from being blocked.
Optimize the image loading process: You can optimize the image loading process by using techniques like image compression, caching, or lazy loading. These techniques can help reduce the amount of data that needs to be loaded, which can help prevent the main thread from being blocked.
Use a different image format: You can use a different image format like WebP or JPEG XR, which are designed to be more efficient and can help reduce the amount of data that needs to be loaded.

By using one or more of these approaches, you can help prevent the main thread from being blocked and improve the performance of your app.
Q&A: Impeller Loading a Large Resolution Image will Block the Main Thread and Cause Animation to Freeze

In our previous article, we discussed the issue of loading a large resolution image in Flutter causing the main thread to be blocked and animation to freeze. In this article, we will provide a Q&A section to help you better understand the issue and its solutions.

Q: What is the main thread in Flutter?

A: The main thread in Flutter is the thread that runs the UI and handles user interactions. It is responsible for rendering the UI, handling events, and updating the state of the app.

Q: Why does loading a large resolution image block the main thread?

A: Loading a large resolution image requires a significant amount of memory and processing power. When an image is loaded, the main thread is responsible for decoding the image, allocating memory for it, and rendering it on the screen. If the image is too large, it can take a significant amount of time to load, which can block the main thread and cause animation to freeze.

Q: What are some common causes of the main thread being blocked?

A: Some common causes of the main thread being blocked include:

Loading large images or videos
Performing complex computations or database queries
Making network requests or API calls
Updating the UI or state of the app

Q: How can I prevent the main thread from being blocked?

A: There are several ways to prevent the main thread from being blocked, including:

Using asynchronous programming to load images or perform complex computations
Using a library or framework that provides a way to load images or perform complex computations in the background
Optimizing the image loading process by using techniques like image compression or caching
Using a different image format that is more efficient

Q: What are some best practices for loading images in Flutter?

A: Some best practices for loading images in Flutter include:

Using a library or framework that provides a way to load images asynchronously
Optimizing the image loading process by using techniques like image compression or caching
Using a different image format that is more efficient
Loading images in the background to prevent the main thread from being blocked

Q: How can I use asynchronous programming to load images in Flutter?

A: You can use asynchronous programming to load images in Flutter by using the Future class or the async/await syntax. For example:

Future<Uint8List> _loadImage(String assetPath) async {
  final ByteData data = await rootBundle.load(assetPath);
  final Uint8List bytes = data.buffer.asUint8List();
  return bytes;
}

Q: What are some popular libraries for loading images in Flutter?

A: Some popular libraries for loading images in Flutter include:

cached_network_image
flutter_cache_manager
image_picker
image_cropper

Q: How can I optimize the image loading process in Flutter?

A: You can optimize the image loading process in Flutter by using techniques like image compression or caching. For example, you can use the flutter_cache_manager library to cache images and reduce the amount of data that needs to be loaded.

Q: What are some best practices for debugging image loading issues in Flutter?

A: Some best practices for debugging image loading issues in Flutter include:

Using the debugPrint function to print out information about the image loading process
Using the flutter inspector to inspect the UI and identify any issues with image loading
Using the flutter doctor command to check for any issues with the Flutter installation or dependencies.