iOS engine restart

On iOS, restart_app creates a new Flutter engine and replaces the Flutter view. The app stays open in the same native process. Configure plugin registration in ios/Runner/AppDelegate.swift before calling Restart.restartApp(). Without this setup, the call returns IOS_ENGINE_RESTART_NOT_CONFIGURED and leaves the app running.

Host setup

Merge the example that matches your app into its existing delegate. Keep your other app initialization code.

UIScene apps

Use this example if your app uses Flutter’s UIScene lifecycle, which is the default for new apps since Flutter 3.41. Keep the initial engine’s plugin registration in didInitializeImplicitFlutterEngine; the configureEngineRestart callback registers plugins for each replacement engine.

import UIKit
import Flutter
import restart_app

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

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

  func didInitializeImplicitFlutterEngine(
    _ engineBridge: FlutterImplicitEngineBridge
  ) {
    GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
  }
}

An existing app must also have Flutter’s UIScene configuration in Info.plist. Follow the Flutter UIScene migration guide if you are upgrading an older host. If you have a custom SceneDelegate, preserve Flutter’s scene callbacks by extending FlutterSceneDelegate or implementing FlutterSceneLifeCycleProvider.

Classic AppDelegate apps

For an older host that registers plugins in didFinishLaunchingWithOptions, keep that registration and add the restart callback:

import UIKit
import Flutter
import restart_app

@main
@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
    )
  }
}

This layout is for the older app lifecycle. Apps built with the iOS 27 SDK must migrate to UIScene. Rebuild the iOS app after changing Swift code. Hot reload does not apply these changes.

Restart from Dart

After setup, the default call uses engine restart on iOS. Call it from an async UI action while the app is active. If you have unsaved data, save it and await the write before this call:

import 'package:restart_app/restart_app.dart';

final result = await Restart.restartApp();

You can also select RestartMode.flutterEngine explicitly. Both calls use the same iOS behavior. A successful result means the request was accepted; the old Dart isolate stops as the engine is replaced.

State after restart

The new engine starts a new Dart root isolate and widget tree, with fresh plugin and platform-view registrations. Data already saved to files, databases, or preferences remains available. The native process stays alive. Swift and Objective-C globals, native singletons, resources retained outside the engine, and unrelated engines or isolates are not reset. Native app launch callbacks do not run again. If your app depends on resetting one of these resources, handle it in the host or plugin that owns it.

Custom windows and native containers

For a standard Flutter app, the plugin selects a visible window in a foreground-active UIWindowScene, preferring its key window, and replaces the root FlutterViewController. If your host owns several windows, pass a windowProvider to configureEngineRestart to select the intended window. Returning nil rejects the request with IOS_NO_ACTIVE_WINDOW instead of selecting another window. If Flutter is embedded inside a native container, also provide a viewControllerInstaller that installs the replacement controller in that container. Without an installer, the plugin rejects a non-Flutter root controller with IOS_UNSAFE_ROOT_REPLACEMENT. For a custom Dart entrypoint, initial route, or engine configuration, use RestartAppPlugin.setEngineFactory. Return a new, running engine with its plugins registered. Do not return the old engine or an engine that failed to start. Use beforeRestart to release host-owned resources before the new engine is created. Use afterRestart to connect custom channels to the new engine after its controller is installed, before the plugin destroys the old engine’s context.

Notification fallback

RestartMode.notificationFallback schedules a local notification and closes the app. The user must tap the notification to reopen it. The default mode never chooses this behavior automatically. From an async UI action, after any required writes have finished:

import 'package:flutter/foundation.dart';
import 'package:restart_app/restart_app.dart';

final result = await Restart.restartApp(
  mode: RestartMode.notificationFallback,
  notificationTitle: 'Update applied',
  notificationBody: 'Tap to reopen the app.',
);
if (!result.success) {
  debugPrint(result.message ?? 'The app could not schedule a restart.');
}

The plugin asks for notification permission if the user has not decided yet. If permission is denied or the notification cannot be scheduled, the result reports failure and the app stays open. Explain that the app will close and require a tap before offering this action. Local notifications do not require the Push Notifications capability.

Start

Guides

Reference

Host setup

UIScene apps

Classic AppDelegate apps

Restart from Dart

State after restart

Custom windows and native containers

Notification fallback

​Host setup

​UIScene apps

​Classic AppDelegate apps

​Restart from Dart

​State after restart

​Custom windows and native containers

​Notification fallback

Host setup

UIScene apps

Classic AppDelegate apps

Restart from Dart

State after restart

Custom windows and native containers

Notification fallback