Hot Reload and Restart in Flutter

What do hot reload and hot restart do?

One of the biggest benefits of using Flutter is that the development experience is fantastic. One part that adds to that experience is Hot Reload and Hot Restart which allows you to see changes updated in your app in real time as you make them.

Debug Bar

To use it you need to be within a debugging session. A debugging session is when you run the application on a device, emulator or website from your IDE (probably VSCode or Android Studio) to see your code working in action. Whilst you’re in the debugging session you will see this bar

debug bar

Whenever you’re in a debug session, this little bar gives you control of the execution of the code.

How Flutter code runs?

When you start a debugging session or compile the code for execution, it turns it into a list of instructions similar to a cooking recipe. Then the computer (specifically the processor) takes those instructions and starts executing them in order.

You can pause the execution by clicking the pause button, and the bar will look like this

debug bar with a paused menu

Going from left to right your options are:

  • Continue - Resume the execution of the code
  • Step Over - If there is a function call, run that function, and then stop the code right after it’s done
  • Step Into - Take the next step of the execution, if there is a function step into that function
  • Step Out - If you stepped into a function, run the rest of the function, and stop where you would have if you did a Step Over
  • Hot Reload - Keep reading this page, we’re going to go deeper into this
  • Hot Restart - Keep reading this page, we’re going to go deeper into this
  • Stop - Ends the debugging session
  • Open DevTools Widget Inspector Page - Opens Widget Inspector Tool

Now let’s actually focus on the title of this doc: these two buttons arrow pointing at hot restart and reload buttons

Hot Reload ⚡️

To understand Hot Reload you need to understand how the Widget Tree works.

Hot Reload is used when you have made some changes to your code and you want to see them reflected in the debugging session you are running. When you press Hot Reload you will magically see your application update with all the changes you implemented.

What’s going on under the hood?

Flutter takes a look through the Widget Tree to find the widgets that could have been affected. Only those widgets that got affected, get re-rendered. This is why it is so fast, and also why the current state of the applications doesn’t get affected. With the default counter app, you notice that the counter stays when you change the color of the app bar for example. That’s because the portion of the Widget Tree that includes the AppBar is not the same as where the counter is.

Side Note

Even if you updated something within the same Widget Tree section of the counter it will still retain the state. This is because the state is stored in something called an Element Tree. When I’m writing this the docs talking about Element Tree are not created. If I forgot about this doc, and you see a doc somewhere talking about Element Tree, please leave an issue so I can link to it here 😊

Hot Restart 🔄

Hot Reload was special because it retains the state of the application, and Hot Restart is here to throw all that away. That’s the big difference between the two. Instead of only rerendering a portion of the Widget Tree, Hot Restart just throws the whole Widget Tree away and starts over.

With Hot Restart you are getting a brand new start to your application. Think of it as stopping the debug session and restarting it again, but way faster.

Side Note

There are still times when you need to completely stop the debugging session, and start it back up. The most common examples are when you add some packages or assets to the pubspec.yaml file. These need to go through the whole process so all the resources get loaded into the device or emulator properly.