restart_app #

Restart or relaunch your Flutter app with a single function call.

Android, macOS, Linux, and Windows use platform-specific relaunch behavior. Web reloads the page. iOS does not provide a public API for automatic full process restart, so restart_app supports an opt-in Flutter engine restart. The old notification-based iOS flow is available only when explicitly requested.

Quick start #

Add the dependency:

dependencies:
  restart_app: ^1.8.2

Import and call:

import 'package:restart_app/restart_app.dart';

final restarted = await Restart.restartApp();

Returns true if the restart was initiated. Returns false on failure (missing iOS engine-restart configuration, missing executable, no launchable activity).

For structured errors and capabilities, use the newer API:

final result = await Restart.restart(
  mode: RestartMode.platformDefault,
);

if (!result.success) {
  // Show or log result.code and result.message.
}

Parameters #

Platform behavior #

iOS #

iOS does not provide a public API for an app to terminate itself and automatically launch a fresh process of the same app. Android-style full process restart is not available on iOS with public APIs.

restart_app supports two iOS behaviors:

1. Flutter engine restart, recommended. This keeps the iOS process alive, creates a new FlutterEngine, runs the Dart entrypoint again, re-registers plugins through the host app's GeneratedPluginRegistrant, creates a new FlutterViewController, replaces the active root view controller, and destroys the old engine context.
2. Notification fallback, legacy and explicit only. This schedules a local notification, calls exit(0), and requires the user to tap the notification to reopen the app. This is not a true restart and is not recommended as normal product behavior.

Configure Flutter engine restart #

The host app owns GeneratedPluginRegistrant, so iOS engine restart requires one app-side setup step.

In ios/Runner/AppDelegate.swift:

import UIKit
import Flutter
import restart_app

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    RestartAppPlugin.configureEngineRestart { engine in
      GeneratedPluginRegistrant.register(with: engine)
    }

    GeneratedPluginRegistrant.register(with: self)

    return super.application(
      application,
      didFinishLaunchingWithOptions: launchOptions
    )
  }
}

Then call:

final result = await Restart.restart(
  mode: RestartMode.flutterEngine,
);

RestartMode.platformDefault uses Flutter engine restart on iOS when this setup is present. If this setup is missing, platformDefault fails cleanly on iOS instead of falling back to notification + exit(0).

iOS capabilities #

final capability = await Restart.restartCapability();

if (capability.flutterEngineRestart) {
  await Restart.restart(mode: RestartMode.flutterEngine);
}

What iOS engine restart resets #

It resets:

• Dart root isolate
• Flutter widget tree
• Flutter engine-owned platform channels
• Flutter plugin registrations for the new engine
• Platform-view factory registrations for the new engine

It does not reset:

• The iOS process
• Swift, Objective-C, C, or C++ static/global state
• Native singleton state
• Native resources retained by plugins
• Unrelated Flutter engines or background isolates
• Native app launch lifecycle callbacks from a real process launch

For code-push systems and plugins with heavy native state, verify behavior in a real release build. Same-process engine restart is not equivalent to full process restart.

Legacy notification fallback #

Use the notification fallback only when the tradeoff is acceptable:

Restart.restart(
  mode: RestartMode.notificationFallback,
  notificationTitle: 'Update applied',
  notificationBody: 'Tap to reopen the app.',
);

The plugin requests notification permission at the moment of restart. If not already granted, iOS shows the system prompt right before exit, which feels abrupt.

Request permission earlier in your app's lifecycle. The permission_handler package works well for this.

If notification permission has been denied, restartApp() returns false and restart() returns a failed result.

Provisioning profiles #

restart_app uses local notifications only, not push notifications. It adds no push-related entitlements to your app.

If you see "requires a provisioning profile with the Push Notifications feature" when exporting an IPA, another dependency is the cause (commonly firebase_messaging). Add the Push Notifications capability to your distribution provisioning profile.

Linux #

Command-line arguments #

By default, the restarted process launches without the original command-line arguments. To preserve them, call restart_app_plugin_store_argv in your linux/main.cc before running the Flutter engine:

#include <restart_app/restart_app_plugin.h>

int main(int argc, char** argv) {
  restart_app_plugin_store_argv(argc, argv);
  // ... rest of main()
}

Most Flutter apps don't rely on command-line arguments, so this step is optional.

Background isolates #

Restart.restartApp() uses a platform channel and must run on the main isolate. Calling it from a background isolate throws:

Bad state: The BackgroundIsolateBinaryMessenger.instance value is invalid
until BackgroundIsolateBinaryMessenger.ensureInitialized is executed.

Send a message from your isolate to the main isolate instead:

// Main isolate: listen for restart signals
final receivePort = ReceivePort();
receivePort.listen((message) {
  if (message == 'restart') {
    Restart.restartApp();
  }
});

// Spawn the isolate with the SendPort
await Isolate.spawn(myIsolateFunction, receivePort.sendPort);

// Background isolate: signal instead of calling restartApp() directly
void myIsolateFunction(SendPort sendPort) {
  // ... your background work ...
  sendPort.send('restart');
}

Requirements #

Dart SDK: >=3.4.0 · Flutter: >=3.22.0

Author #

Created by Soroush Yousefpour