Skip to content
pubscout

flutter_single_instance

1.7.0, released a year ago by mcquenji.dev

Check if your Flutter application is already running and bring it to the foreground.

$ flutter pub add flutter_single_instance
Source repository

What it does

Allows desktop apps to check if another instance of the same application is currently running. If an instance is found, it can focus the existing window and exit the new instance.

AI-written summary of version 1.7.0, based on the package's README and metadata. Report an inaccuracy

Use it when

  • You are building a desktop application for macOS, Windows, or Linux that should only have a single running instance.
  • You need to focus the already running window when a user tries to launch a second instance.

Skip it when

  • You are building primarily for mobile or web platforms where this package always reports as the first instance.
  • You require robust single-instance support on Android or iOS.

Strengths

  • Provides confirmed working support for macOS, Windows, and Linux.
  • Supports focusing the running instance using built-in RPC capabilities.
  • Includes a debug mode feature to bypass single-instance checks during development.

Weaknesses

  • Always reports as the first instance on Android, iOS, and Web.
  • Requires manual configuration of app sandbox and network entitlements on macOS.

Setup

Kind
Flutter widgets
Effort
Low
Code generation
Yes (build_runner)
Direct dependencies
7

On macOS, you must disable sandboxing and enable server/client networking entitlements in your .entitlements files.

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await windowManager.ensureInitialized();

  if (await FlutterSingleInstance().isFirstInstance()) {
    runApp(const MyApp());
  } else {
    print("App is already running");
    final err = await FlutterSingleInstance().focus();
    exit(0);
  }
}

Works with

Packages commonly used together with flutter_single_instance: ones it builds on, ones built on it, and its own family.