Contents

Flutter's build modes

Contents

The Flutter tooling supports three modes when compiling your app, and a headless mode for testing. You choose a compilation mode depending on where you are in the development cycle. Are you debugging your code? Do you need profiling information? Are you ready to deploy your app?

A quick summary for when to use which mode is as follows:

  • Use debug mode during development, when you want to use hot reload.
  • Use profile mode when you want to analyze performance.
  • Use release mode when you are ready to release your app.

The rest of the page goes into more detail about these modes. For information on headless testing, see the Flutter wiki.

Debug

In debug mode, the app is set up for debugging on the physical device, emulator, or simulator.

Debug mode for mobile apps mean that:

  • Assertions are enabled.
  • Service extensions are enabled.
  • Compilation is optimized for fast development and run cycles (but not for execution speed, binary size, or deployment).
  • Debugging is enabled, and tools supporting source level debugging (such as DevTools) can connect to the process.

Debug mode for a web app means that:

  • The build is not minified and tree shaking has not been performed.
  • The app is compiled with the dartdevc compiler for easier debugging.

By default, flutter run compiles to debug mode. Your IDE supports this mode. Android Studio, for example, provides a Run > Debug… menu option, as well as a green bug icon overlayed with a small triangle on the project page.

Release

Use release mode for deploying the app, when you want maximum optimization and minimal footprint size. For mobile, release mode (which is not supported on the simulator or emulator), means that:

  • Assertions are disabled.
  • Debugging information is stripped out.
  • Debugging is disabled.
  • Compilation is optimized for fast startup, fast execution, and small package sizes.
  • Service extensions are disabled.

Release mode for a web app means that:

  • The build is minified and tree shaking has been performed.
  • The app is compiled with the dart2js compiler for best performance.

The command flutter run --release compiles to release mode. Your IDE supports this mode. Android Studio, for example, provides a Run > Run… menu option, as well as a triangular green run button icon on the project page. You can compile to release mode for a specific target with flutter build <target>. For a list of supported targets, use flutter help build.

For more information, see the docs on releasing iOS and Android apps.

Profile

In profile mode, some debugging ability is maintained—enough to profile your app’s performance. Profile mode is disabled on the emulator and simulator, because their behavior is not representative of real performance. On mobile, profile mode is similar to release mode, with the following differences:

  • Some service extensions, such as the one that enables the performance overlay, are enabled.
  • Tracing is enabled, and tools supporting source-level debugging (such as DevTools) can connect to the process.

Profile mode for a web app means that:

  • The build is not minified but tree shaking has been performed.
  • The app is compiled with the dart2js compiler.
  • DevTools can’t connect to a Flutter web app running in profile mode. Use Chrome DevTools to generate timeline events for a web app.

Your IDE supports this mode. Android Studio, for example, provides a Run > Profile… menu option. The command flutter run --profile compiles to profile mode.

For more information on the build modes, see Flutter’s build modes.