Package selection guidance compiled from public package information, community data, and project usage.
Workmanager is a Flutter plugin that enables scheduling background tasks on both Android and iOS platforms. It allows developers to run periodic or one-time jobs even when the app is terminated, making it ideal for tasks like syncing data, fetching updates, or processing files in the background. The plugin integrates with native background execution services, ensuring reliable task execution within system constraints. It supports both foreground and background modes, with configurable intervals and conditions.
Use cases
Scheduled data synchronization
Background file processing
Periodic API polling
Push notification handling
Battery-efficient task execution
Key features
Cross-platform background tasks
Support for periodic and one-time jobs
Configurable execution intervals
Integration with native OS background services
Low battery and power optimization
Suitable for
Apps needing reliable background execution
Data-intensive applications
Offline-first applications
Apps requiring regular updates without user interaction
Developers targeting both Android and iOS
Considerations
Limited on iOS due to stricter background execution policies
Requires proper configuration of background modes in Xcode
May be restricted by device power-saving features
Not suitable for time-critical tasks
Needs testing on real devices for reliability
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
Flutter Workmanager
Execute Dart code in the background, even when your app is closed (Android and iOS). On macOS, background tasks run while the app is running or backgrounded and the Mac is awake. Perfect for data sync, file uploads, and periodic maintenance tasks.
⚠️ Experimental web support now exists via workmanager_web (Service
Worker + Web Worker based background execution). See the
Web (experimental) page and the
package README for honest limitations and how to
test it in Chrome.
→ Troubleshooting Guide - Why tasks stop after app close (OEM battery optimization, constraints, verification)
🎯 Use Cases
Background tasks are perfect for:
Sync data from API - Keep your app's data fresh
Upload files in background - Reliable file uploads
Clean up old data - Remove old files and cache
Fetch notifications - Check for new messages
Database maintenance - Optimize and clean databases
⏱ Long-Running Tasks (Android)
For work that takes longer than the regular background execution window (bulk
uploads/downloads, ML processing), Android tasks can run as a foreground
service with a persistent notification. Pass a foregroundServiceConfig to
registerOneOffTask or registerPeriodicTask:
awaitWorkmanager().registerOneOffTask(
"upload-task",
"upload_files",
foregroundServiceConfig: ForegroundServiceConfig(
notificationTitle: "Uploading files",
notificationText: "Your files are being uploaded",
),
);
cancelByUniqueName, cancelByTag and cancelAll stop the WorkManager worker
immediately, but the Dart callback that is currently running keeps executing
unless it reacts to the stop. Pass an onTaskStopped handler to executeTask
inside your callbackDispatcher to be notified when a running task is stopped
before it finishes:
@pragma('vm:entry-point')
voidcallbackDispatcher() {
Workmanager().executeTask(
(taskName, inputData) async {
returntrue;
},
onTaskStopped: (taskName, stopReason) async {
// Mark the task as cancelled / persist state, then return promptly.
},
);
}
The handler receives the task name and the WorkManager stop reason
(cancelledByApp, timeout, preempt, ...); on Android < 12 the reason is
StopReason.unknown. Android-only — iOS has no way to stop a running task.
See the Customization guide
for details.
