Hot Reload vs Hot Restart in Flutter: The Beginner’s Complete Guide (2026)

You save your file. Nothing changes. You press hot reload again. Still nothing. So you hit hot restart — and suddenly the app works, but your counter reset to zero and you lost your place three screens deep. Sound familiar?

This is the single most common frustration for Flutter beginners, and it comes down to one misunderstanding: hot reload and hot restart are not interchangeable. They do fundamentally different things. Once you understand the difference — really understand it — you will know exactly which one to reach for every single time, and you will stop losing state by accident.

This guide covers everything: what each tool actually does under the hood, every situation where hot reload silently fails, when you must use hot restart, the keyboard shortcuts, the most common beginner mistakes with ❌/✅ code pairs, and six interview questions you will almost certainly be asked.

1. The Core Difference (One Sentence Each)

Hot reload injects your updated Dart code into the running app and rebuilds the widget tree — without restarting the app or touching its current state.

Hot restart stops the running app, compiles your latest code, and relaunches it from main() — as if you pressed the Play button for the first time.

That is the entire distinction. Everything else — when each one works, when each one fails, why your counter reset — follows directly from those two definitions.

2. Quick Comparison Table

3. What Hot Reload Does — And How It Works

When you trigger a hot reload, Flutter compiles your changed Dart files and injects the updated bytecode directly into the already-running Dart VM. It then calls build() on every widget from the root down, so your UI reflects the new code.

The critical word is inject. The app never stops. The Dart VM keeps running. All variables that were holding values keep their values. All controllers, streams, and navigation history stay intact. Only the widget tree is rebuilt.

Here is a mental model of what happens step by step:

1. You save your Dart file
2. Flutter's tooling detects the change
3. Only the changed files are recompiled
4. Updated bytecode is injected into the running Dart VM
5. Flutter calls build() on the root widget downward
6. Your UI updates — your state is untouched

4. Hot Reload: Best Use Cases with Code Examples

Hot reload shines for anything that lives purely in the widget build() method. Here are the concrete use cases with runnable examples.

Changing UI text, colors, and sizing

Run the app below, tap the button a few times to increment the counter, then change "Hot Reload Demo" to "My Updated App" and change Colors.blue to Colors.green. Save. The title and color update instantly — and your counter value stays exactly where it was.

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: CounterPage()));
}

class CounterPage extends StatefulWidget {
  const CounterPage({super.key});

  @override
  State<CounterPage> createState() => _CounterPageState();
}

class _CounterPageState extends State<CounterPage> {
  int count = 0;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Hot Reload Demo'),  // ← change this text, hot reload
        backgroundColor: Colors.blue,          // ← change this color, hot reload
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              'Count: $count',
              style: const TextStyle(fontSize: 32, fontWeight: FontWeight.bold),
            ),
            const SizedBox(height: 24),
            ElevatedButton(
              onPressed: () => setState(() => count++),
              child: const Text('Tap to Increase'),
            ),
          ],
        ),
      ),
    );
  }
}

Iterating on a screen deep in the navigation stack

Without hot reload you would need to: stop the app → edit the code → restart → tap through multiple screens. With hot reload you stay on that screen and iterate freely:

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: ScreenOne()));
}

class ScreenOne extends StatelessWidget {
  const ScreenOne({super.key});
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Screen 1')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => Navigator.push(
            context, MaterialPageRoute(builder: (_) => const ScreenTwo()),
          ),
          child: const Text('Go to Screen 2'),
        ),
      ),
    );
  }
}

class ScreenTwo extends StatelessWidget {
  const ScreenTwo({super.key});
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Screen 2')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => Navigator.push(
            context, MaterialPageRoute(builder: (_) => const ScreenThree()),
          ),
          child: const Text('Go to Screen 3'),
        ),
      ),
    );
  }
}

class ScreenThree extends StatelessWidget {
  const ScreenThree({super.key});
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Screen 3')),
      body: const Center(
        // Navigate here once, then freely edit this widget and hot reload.
        // You stay on Screen 3 — no need to navigate back every time.
        child: Text(
          'Edit me freely with hot reload!',
          style: TextStyle(fontSize: 24, color: Colors.deepPurple), // ← tweak
        ),
      ),
    );
  }
}

5. When Hot Reload Silently Fails

This is the section most beginners never read — and it explains almost every “hot reload didn’t work” complaint in forums or on Stack Overflow. Flutter reports a successful reload even when none of your visible changes took effect.

6. What Hot Restart Does — And When You Need It

Hot restart discards the current VM state entirely, compiles your latest Dart code, and runs the app from main() again — exactly like pressing the Play button. Everything in memory is gone: all variable values return to their declared initial values, navigation history is cleared, and every widget’s initState() runs fresh. Hot restart still completes in 2–5 seconds because it skips rebuilding the native shell.

7. Hot Restart: Best Use Cases with Code Examples

Changes to initState()

Run this app and watch the debug console. Tap the button a few times. Then change the string assigned in initState() and hot reload — nothing happens. Now press R (hot restart) — the updated message appears immediately and the counter resets to 0:

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: RestartDemoPage()));
}

class RestartDemoPage extends StatefulWidget {
  const RestartDemoPage({super.key});

  @override
  State<RestartDemoPage> createState() => _RestartDemoPageState();
}

class _RestartDemoPageState extends State<RestartDemoPage> {
  int count = 0;
  String welcomeMessage = '';

  @override
  void initState() {
    super.initState();
    // Try changing this string and hot reloading — nothing happens.
    // Hot restart (R) will apply the change.
    welcomeMessage = 'App started!';
    debugPrint('initState ran: $welcomeMessage');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Hot Restart Demo')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(welcomeMessage, style: const TextStyle(fontSize: 18)),
            const SizedBox(height: 16),
            Text('Count: $count', style: const TextStyle(fontSize: 32, fontWeight: FontWeight.bold)),
            const SizedBox(height: 24),
            ElevatedButton(
              onPressed: () => setState(() => count++),
              child: const Text('Increase'),
            ),
          ],
        ),
      ),
    );
  }
}

Changes to global variables

import 'package:flutter/material.dart';

// Global variable — hot reload will NOT update this initial value.
// Change 'Guest' to 'Alice' and hot reload: still shows 'Guest'.
// Hot restart: correctly shows 'Alice'.
String currentUser = 'Guest';

void main() {
  runApp(const MaterialApp(home: GlobalVarDemo()));
}

class GlobalVarDemo extends StatelessWidget {
  const GlobalVarDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Global Variable Demo')),
      body: Center(
        child: Text(
          'Logged in as: $currentUser',
          style: const TextStyle(fontSize: 22),
        ),
      ),
    );
  }
}

Changes to app-level configuration in main()

import 'package:flutter/material.dart';

void main() {
  // Any change here requires hot restart — not hot reload.
  WidgetsFlutterBinding.ensureInitialized();

  runApp(
    MaterialApp(
      // Change this seed color — hot reload will NOT apply it.
      // Press R to hot restart and see the new theme.
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const MyHomePage(),
    ),
  );
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(
        child: Text(
          'Change the theme seed color above and hot restart',
          textAlign: TextAlign.center,
        ),
      ),
    );
  }
}

8. Keyboard Shortcuts and IDE Buttons

9. Hot Restart vs Full Restart — Not the Same Thing

10. Common Beginner Mistakes

Mistake 1: Expecting hot reload to apply initState() changes

❌ Changing initState() and pressing hot reload — the change is silently ignored:

@override
void initState() {
  super.initState();
  // You changed 'App started!' to 'Welcome back!' and hot reloaded.
  // Nothing happens — initState() does not re-run on hot reload.
  welcomeMessage = 'Welcome back!';
}

✅ Press R (hot restart) when you change anything inside initState():

@override
void initState() {
  super.initState();
  welcomeMessage = 'Welcome back!';
  // After saving this, press R in the terminal or click Hot Restart.
  // initState() runs fresh and the new message appears immediately.
}

Mistake 2: Hot restarting when you only changed a visual — losing all state

❌ Changed a button color but pressed R — counter reset to 0 unnecessarily:

ElevatedButton(
  style: ElevatedButton.styleFrom(backgroundColor: Colors.red), // changed color
  onPressed: () => setState(() => count++),
  child: const Text('Tap'),
)
// You pressed R — count reset to 0 unnecessarily.

✅ For purely visual changes, always reach for lowercase r (hot reload) first:

ElevatedButton(
  style: ElevatedButton.styleFrom(backgroundColor: Colors.red), // changed color
  onPressed: () => setState(() => count++),
  child: const Text('Tap'),
)
// Press r (lowercase) — color updates instantly, count stays where it was.

Mistake 3: Using hot restart after adding a new plugin

# ❌ pubspec.yaml — you just added this plugin and tried hot restart:
dependencies:
  shared_preferences: ^2.2.2  # NEW — hot restart will NOT pick this up

# ✅ Stop the app first (q), then:
# flutter pub get
# flutter run

Mistake 4: Hot reloading after changing a global variable’s initial value

// ❌ You change this to 100 and hot reload. The app still shows 0.
int startingScore = 0;

// ✅ Change the value, then press R (hot restart).
// The Dart VM starts fresh and reads the new initial value.
int startingScore = 100;

11. Interview Q&A

These are the questions you will be asked in Flutter interviews as a beginner or junior developer.

12. Related Posts