flutter_full_restart 2.1.0

flutter_full_restart: ^2.1.0 copied to clipboard

Restart a Flutter app from Dart, on every platform.
Built and maintained by Azerosoft.

flutter_full_restart restarts your app the way a user would by closing and reopening it, or rebuilds just the UI in place.

await FullRestart.restart();                     // kill the process and cold-start the app
await FullRestart.restart(type: RestartType.ui); // rebuild the UI in place

_{UI restart and full restart in the example app on iOS and Android.}

Contents #

• Features
• Platform support
• Requirements
• Installation
• Quick start
• Usage
• API overview
• How it works
• Platform setup
• Troubleshooting
• Example app
• Tested with
• Contributing
• About Azerosoft

Features #

• Full restart. Kills the process and cold-starts the app, exactly like closing and reopening it. On iOS it starts a new Flutter engine instead, unless you opt in to a process restart.
• UI restart. Keeps the process and rebuilds the whole widget tree from scratch, for example after a language or theme change.
• Every platform. Android, iOS, macOS, Web (including WebAssembly), Windows and Linux.
• No setup. Add the package and call it. No platform needs native code or manifest changes.
• Swift Package Manager ready. iOS and macOS work with Swift Package Manager and CocoaPods, privacy manifest included.
• Never throws. Every call returns true or false, so a failed restart never crashes your app.

Platform support #

On the web, both restart types reload the page.

Requirements #

Installation #

flutter pub add flutter_full_restart

No platform needs any setup. On iOS you can register a URL scheme so that a full restart restarts the native process too, see iOS: restart the whole process.

Quick start #

Wrap your app in FullRestartScope so a UI restart can rebuild everything:

import 'package:flutter/material.dart';
import 'package:flutter_full_restart/flutter_full_restart.dart';

void main() {
  runApp(const FullRestartScope(child: MyApp()));
}

Then restart from anywhere:

await FullRestart.restart();

Usage #

Full restart #

Kills the process and launches the app again. Use it after installing an update, changing the backend environment or anything else that needs a clean start.

await FullRestart.restart();

UI restart #

Keeps the process and rebuilds the Flutter UI from scratch. Every State below FullRestartScope is disposed and created again.

await FullRestart.restart(type: RestartType.ui);

Handle UI restarts yourself #

If you would rather not wrap the app in FullRestartScope, register a callback. It runs instead of the automatic rebuild:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  FullRestart.ensureInitialized(onUiRestart: () {
    // For example: reset your state management and go to the first screen.
  });
  runApp(const MyApp());
}

Read links with app_links or a similar package #

On iOS, when the app registers the URL scheme, a full restart reopens the app through an empty link (<bundle id>://). Flutter's own deep linking never sees it, but packages that read links themselves, such as app_links, report it after the restart. Skip it with FullRestart.isRestartLink:

AppLinks().uriLinkStream.listen((Uri uri) {
  if (FullRestart.isRestartLink(uri)) return; // the link of a full restart
  router.go(uri.path); // https://example.com/product/42 -> /product/42
});

Your other links, with or without the app running, arrive as usual.

API overview #

Options of restart:

The full API reference is on pub.dev.

How it works #

RestartType.full #

• Android: starts the launcher activity in a new task and exits the process.
• iOS: starts a new Flutter engine in the running process, so main() runs again with fresh Dart state. If the app registers its bundle identifier as a URL scheme, it instead reopens the app through that scheme and exits, like the other platforms. See iOS: restart the whole process.
• macOS: launches a new instance of the app bundle and exits.
• Windows and Linux: start a new instance of the executable with the same arguments and exit.
• Web: reloads the page.

RestartType.ui #

• Android: recreates the Flutter activity, which boots a new Flutter engine, so main() runs again.
• iOS: replaces the root FlutterViewController on the same engine and rebuilds the widget tree via FullRestartScope.
• macOS, Windows and Linux: keep the window and the engine and rebuild the widget tree via FullRestartScope.
• Web: reloads the page.

Platform setup #

iOS: restart the whole process (optional) #

iOS works without any setup. There, a full restart starts a new Flutter engine inside the running process: main() runs again, all Dart state is gone and every plugin is registered again.

iOS lets an app reopen itself only through its own URL scheme. If the native side should start over too, register your bundle identifier as a URL scheme in ios/Runner/Info.plist. A full restart then reopens the app through that scheme and exits the old process, like on the other platforms:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    </array>
  </dict>
</array>

The plugin keeps the URL it reopens the app with away from Flutter's deep linking, so your router never sees it. If you read links with a package such as app_links, skip it as shown in Read links with app_links. Your app's other URLs are not affected.

Register the URL scheme if your app keeps state on the native side that must start over, sets up its own platform channels in AppDelegate, or uses Shorebird code push: Shorebird applies a patch only when the process restarts. On Android, a full restart always restarts the process, so patches are applied there without any setup.

Apple discourages apps from quitting on their own. With the URL scheme, trigger a full restart only in response to a user action, such as switching the language or the backend environment.

Swift Package Manager #

Nothing to configure. When Swift Package Manager is enabled (the default in recent Flutter versions), Flutter uses the plugin's Package.swift on iOS and macOS. Otherwise it falls back to CocoaPods. Both include a privacy manifest (PrivacyInfo.xcprivacy).

Android #

The Android side is written in Java on purpose: it builds with any Android Gradle Plugin from 7.x to 9.x, with or without the Kotlin Gradle Plugin. No setup is needed.

Troubleshooting #

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
    end
  end
end

Example app #

The example app shows what each kind of restart resets: the time the Dart session started and the time the screen was built. The animations at the top of this page were recorded with it. It runs on all six platforms.

cd example
flutter run

Tested with #

The minimum and maximum versions this package was tested with, as of October 2026. Versions in between were not all tested one by one, but they are expected to work as well. On every push, GitHub Actions runs the tests and builds the example for all platforms, once with Flutter 3.22.3 and once with the latest stable release.

Flutter and Dart #

Android #

iOS #

macOS #

Windows #

Linux #

Web #

Tried by hand #

The example app was also started on these systems and the restarts were tried by hand:

The Windows and Linux C++ unit tests also run on every push, on Windows Server 2022 and 2025 and on Ubuntu 24.04 (x64).

Contributing #

Bug reports, ideas and pull requests are welcome. Please read the contributing guide and our code of conduct first.

• Report a bug
• Request a feature
• Report a security issue (privately, please)

About Azerosoft #

Azerosoft is a design and development studio from Baku, Azerbaijan. We design interfaces and build websites, web and mobile apps, backends, CRM systems and 2D games. We use our packages in our own projects and maintain them for everyone.

• Website: azerosoft.com
• All our packages: pub.dev/publishers/azerosoft.com
• GitHub: github.com/azerosoft
• Email: hello@azerosoft.com

Building something with Flutter? Tell us about your project.

License #

Released under the MIT License.