Why doesn't hot reload apply my change in Flutter, and when do I need hot restart?

What hot reload does

It injects the updated source into the running Dart VM and rebuilds the widget tree, keeping the app state. Only code that is executed again is affected, which means anything that ran once already is not re-run.

Changes that need hot restart (state reset)

• Initial values of fields and global variables or static fields (initialisers have already run).
• Code in main() and initState() of an already mounted widget.
• Changing enums, converting a StatelessWidget to StatefulWidget (sometimes works), changing generic type arguments.
• Adding a new const instance whose value is cached.

Hot restart (R in the terminal, shift-cmd-R or the restart icon) recompiles and restarts the app, losing state.

Changes that need a full stop and run

• Native code and platform config: AndroidManifest, Info.plist, Gradle files, Podfile, pubspec.yaml assets, new plugins.
• Anything in android/ or ios/.
• Changing --dart-define values.

If reload says 0 libraries or errors

• The file has a compile error; the terminal shows it above the reload message.
• Reload is disabled in release/profile builds; use flutter run in debug.
• Files outside lib/ such as generated code need the generator to run first (build_runner watch).
• On web, hot reload for web is available in recent Flutter versions but may be limited; check your channel notes, and fall back to restart.

Habit that avoids confusion

Put things you want to tweak live inside build or a getter, not in a field initialiser. When in doubt, press R; it is fast.

Pitfall

An app stuck on stale code after switching branches: run flutter clean, then rebuild.