Flutter Background Tasks with the workmanager Package

Some work shouldn’t require an open app: syncing data, uploading files, cleaning caches, checking for new messages, optimizing a database. The workmanager package wraps each platform’s native scheduling API behind one Dart API, so you can execute Dart code in the background — even when your app is closed.

Source: workmanager on pub.dev, Flutter Community (fluttercommunity.dev).

How it works

The core API has two pieces: an entry-point callback dispatcher and task registration.

@pragma('vm:entry-point')
void callbackDispatcher() {
  Workmanager().executeTask((task, inputData) async {
    print("Background task: $task");
    // Your background work here
    return Future.value(true);
  });
}

void main() {
  Workmanager().initialize(callbackDispatcher);
  Workmanager().registerOneOffTask("task-id", "simpleTask");
  runApp(MyApp());
}

Two details are easy to miss:

• @pragma('vm:entry-point') prevents the AOT compiler from tree-shaking the callback. Without it, your background task silently disappears in release builds.
• Return a Future<bool> — true marks the task successful, false signals failure so the platform scheduler can apply retry/backoff policy.

Under the hood: a federated plugin

workmanager uses Flutter’s federated plugin architecture, with platform implementations split across packages:

Package	Platform	Mechanism
workmanager	all	Unified API
workmanager_android	Android	WorkManager
workmanager_apple	iOS / macOS	BGTaskScheduler / NSBackgroundActivityScheduler
workmanager_web	Web	Service Worker + Web Worker (experimental)
workmanager_linux	Linux	systemd user units (experimental)

That structure is why adding a new platform doesn’t mean rewriting the API — and why the main package can stay lightweight.

Platform realities worth knowing

Android gets the full WorkManager story: constraints (charging, network), periodic tasks, and OS-driven deferral under battery optimization. This is the platform where background execution is most predictable.

iOS and macOS run through BGTaskScheduler and NSBackgroundActivityScheduler respectively — and the README is explicit: tasks run while the app is running or backgrounded, not after the user quits it. iOS gives no guarantees about when a task fires; the system decides based on budget and device conditions.

Web (workmanager_web, experimental) maps periodic tasks to Periodic Background Sync and executes the compiled Dart callback inside the Service Worker when the page is closed. The limitations are stated honestly: no exact scheduling, Chromium-only, requires an installed PWA, and a Flutter-free dispatcher.

Linux (workmanager_linux, experimental) uses systemd user units — systemd-run transient units for one-off tasks and .timer/.service pairs for periodic ones, with Persistent=true catch-up after downtime. Tasks relaunch your app in headless --background-task mode. Constraints, backoff, and tags aren’t supported yet, and a systemd user session is required.

Use cases where it shines

• Data sync — refresh a local cache on a schedule.
• Reliable uploads — retry a failed file upload when connectivity returns.
• Cleanup — expire old records, purge temporary files.
• Notifications — poll an endpoint for new messages.
• Database maintenance — vacuum or reindex on a cadence.

Designing for the constraints

Background execution is a cooperative feature — the OS is the senior partner. Practical guidance:

1. Idempotency first. Your task will sometimes run twice or run late. Make re-runs safe.
2. Keep it short. Long-running work risks being killed; chunk it or hand off to a foreground service where the platform allows.
3. Don’t schedule what a push notification does better. For event-driven wakeups, FCM is the right tool; workmanager is for scheduled work.
4. Test on device, not just emulator. Battery optimization (especially on Chinese OEM Android builds) changes real-world behavior substantially.
5. Version-pin and read the changelog. The package sits at 0.10.x with active platform-package updates.

Getting started

Full docs — quick start, API reference, and a debugging guide — live at docs.page/fluttercommunity/flutter_workmanager, with a complete example app in the repo’s example/ folder. The package is MIT-licensed, published by the verified fluttercommunity.dev publisher, and dependency-wise pulls only flutter plus its platform packages.

If your app needs to do work when nobody’s looking, workmanager remains the community-standard place to start.