Dart isolates allow you to move CPU-intensive work away from your application’s main isolate. This can help keep a Flutter application’s animations, scrolling, and user interactions responsive while expensive calculations happen independently.
Two important APIs you will encounter are:
Isolate.run()
and:
Isolate.spawn()
Both can execute Dart code in another isolate, but they are designed for different situations.
The simplest way to remember the difference is:
Use
Isolate.run()for one-off background computations. UseIsolate.spawn()when you need a longer-lived worker isolate and more control over communication and lifecycle.
For example:
One heavy task
↓
Isolate.run()
Repeated tasks
↓
Persistent worker
↓
Isolate.spawn()
In this guide, we will compare Isolate.run() and Isolate.spawn() with practical examples and understand when each one makes sense in a real Flutter application.
Quick Comparison
| Feature | Isolate.run() | Isolate.spawn() |
|---|---|---|
| Best for | One-off tasks | Long-running/custom workers |
| Setup | Simple | More manual |
| Result handling | Direct Future result | Usually ports/messages |
| Communication | Mostly abstracted | Manual |
| Lifecycle | Automatically managed | Developer can manage it |
SendPort needed | Usually no | Commonly yes |
ReceivePort needed | Usually no | Commonly yes |
| Repeated tasks | Usually not ideal | Good fit |
| Error handling | Simple | More control/setup |
| Code complexity | Low | Higher |
Neither API is universally better.
The correct choice depends on the workload.
First: What Is a Dart Isolate?
A Dart isolate is an independent execution context with its own memory and event loop.
A typical Flutter application has a main isolate responsible for Dart-side application work.
Conceptually:
Main Isolate
│
├── State updates
├── User interactions
├── Widget-related work
└── Application logic
Suppose you execute a large synchronous calculation:
final result = calculatePrimeNumbers(1000000);
If this takes a long time on the main isolate, other Dart work on that isolate must wait.
That can contribute to:
Frozen UI
Janky animations
Delayed interactions
Dropped frames
Instead, the calculation can run in another isolate.
Main Isolate Worker Isolate
UI remains active ────────► Heavy calculation
│ │
│ │
│ Result
│ │
◄────────────────────────────┘
Both Isolate.run() and Isolate.spawn() can help create this separation.
The main difference is how the worker is managed.
What Is Isolate.run()?
Isolate.run() is a high-level Dart API designed to make one-off isolate work easy.
Import:
import 'dart:isolate';
Then:
final result = await Isolate.run(() {
return heavyCalculation();
});
Or simply:
final result = await Isolate.run(
heavyCalculation,
);
The API handles much of the isolate lifecycle for you.
Conceptually:
Main Isolate
│
│ Isolate.run()
▼
New Isolate
│
│ Execute function
▼
Result
│
▼
Main Isolate
Worker finishes
You provide a computation and await the result.
Basic Isolate.run() Example
Suppose we have:
int calculateSum() {
var total = 0;
for (var i = 0; i < 100000000; i++) {
total += i;
}
return total;
}
Running directly:
final result = calculateSum();
means the calculation executes on the current isolate.
Instead:
final result = await Isolate.run(
calculateSum,
);
Now the expensive calculation can run independently from the main isolate.
Then:
print(result);
receives the final result.
What Happens Inside Isolate.run()?
At a high level:
1. Call Isolate.run()
↓
2. Dart creates worker isolate
↓
3. Worker executes computation
↓
4. Result is transferred back
↓
5. Worker isolate exits
↓
6. Future completes
Most of this lifecycle is hidden from you.
That is why the code can remain as simple as:
final result = await Isolate.run(
heavyCalculation,
);
Real Flutter Example with Isolate.run()
Imagine a Flutter screen that performs an expensive calculation.
class CalculationScreen extends StatefulWidget {
const CalculationScreen({
super.key,
});
@override
State<CalculationScreen> createState() =>
_CalculationScreenState();
}
class _CalculationScreenState
extends State<CalculationScreen> {
bool loading = false;
int? result;
Future<void> calculate() async {
setState(() {
loading = true;
});
final value = await Isolate.run(() {
var total = 0;
for (var i = 0; i < 100000000; i++) {
total += i;
}
return total;
});
if (!mounted) return;
setState(() {
result = value;
loading = false;
});
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text(
'Isolate.run Example',
),
),
body: Center(
child: Column(
mainAxisAlignment:
MainAxisAlignment.center,
children: [
if (loading)
const CircularProgressIndicator(),
if (result != null)
Text(
'Result: $result',
),
const SizedBox(height: 20),
ElevatedButton(
onPressed:
loading ? null : calculate,
child: const Text(
'Start Calculation',
),
),
],
),
),
);
}
}
The important section is:
final value = await Isolate.run(() {
// Expensive CPU work
});
The main isolate can continue processing UI work while the worker performs the computation.
When Isolate.run() Works Best
Isolate.run() works especially well for tasks shaped like:
Input
↓
Process
↓
Result
For example:
Large JSON
↓
Parse
↓
Models
or:
Large dataset
↓
Filter + sort + aggregate
↓
Processed result
or:
Raw data
↓
Expensive calculation
↓
Final value
These are finite tasks.
The worker does its job, returns the result, and exits.
Example: Large JSON Parsing with Isolate.run()
Suppose your API returns a very large JSON payload.
The network request itself is asynchronous:
final response = await http.get(url);
However, parsing a sufficiently large payload can become CPU-intensive.
Instead of:
final data = jsonDecode(
response.body,
);
you could use:
final data = await Isolate.run(() {
return jsonDecode(
response.body,
);
});
For model conversion:
final users = await Isolate.run(() {
final decoded =
jsonDecode(response.body)
as List<dynamic>;
return decoded
.map(
(json) => User.fromJson(
json as Map<String, dynamic>,
),
)
.toList();
});
This can be useful when parsing is large enough to measurably affect UI responsiveness.
Do not use an isolate for tiny JSON responses simply because JSON parsing exists.
Example: Large List Processing
Suppose you need to process a large list.
List<int> processNumbers(
List<int> numbers,
) {
return numbers
.where(
(number) => number.isEven,
)
.map(
(number) => number * number,
)
.toList();
}
You can execute:
final result = await Isolate.run(
() => processNumbers(numbers),
);
Again:
One task
↓
One result
This is an excellent fit for Isolate.run().
What Is Isolate.spawn()?
Isolate.spawn() is a lower-level API.
It gives you more direct control over the isolate and is particularly useful when the worker needs to remain alive.
Basic syntax:
await Isolate.spawn(
workerFunction,
message,
);
For example:
void worker(String message) {
print(message);
}
Then:
await Isolate.spawn(
worker,
'Hello worker',
);
Unlike Isolate.run(), however, real Isolate.spawn() architectures often involve explicit message communication.
That means working with:
ReceivePort
and:
SendPort
Why Does Isolate.spawn() Need Ports?
Isolates do not communicate through normal shared mutable variables.
Instead, they send messages.
Conceptually:
Main Isolate
│
│ Message
▼
Worker Isolate
Worker Isolate
│
│ Result
▼
Main Isolate
Dart provides ports for this communication.
SendPort
↓
Message
↓
ReceivePort
Basic Isolate.spawn() Example
Let’s create a worker that calculates a sum.
void calculateSum(
SendPort sendPort,
) {
var total = 0;
for (var i = 0; i < 100000000; i++) {
total += i;
}
sendPort.send(total);
}
Now create a ReceivePort:
final receivePort =
ReceivePort();
Spawn the worker:
await Isolate.spawn(
calculateSum,
receivePort.sendPort,
);
Receive the result:
final result =
await receivePort.first;
print(result);
Then clean up:
receivePort.close();
Complete function:
Future<void> runCalculation() async {
final receivePort =
ReceivePort();
await Isolate.spawn(
calculateSum,
receivePort.sendPort,
);
final result =
await receivePort.first;
print(
'Result: $result',
);
receivePort.close();
}
Compare the Same Task
Using Isolate.run():
final result = await Isolate.run(() {
return calculateSum();
});
Using Isolate.spawn():
final receivePort =
ReceivePort();
await Isolate.spawn(
calculateSumWorker,
receivePort.sendPort,
);
final result =
await receivePort.first;
receivePort.close();
For a simple one-time calculation, Isolate.run() is clearly easier.
Therefore:
One calculation
↓
Isolate.run()
is usually preferable.
Then Why Use Isolate.spawn()?
Because not every worker should immediately exit after returning one value.
Imagine an image-processing application.
The user processes:
Image 1
Image 2
Image 3
Image 4
Image 5
Using a one-off model might conceptually look like:
Image 1
→ Create isolate
→ Process
→ Destroy isolate
Image 2
→ Create isolate
→ Process
→ Destroy isolate
Image 3
→ Create isolate
→ Process
→ Destroy isolate
For frequent tasks, repeatedly creating workers may not be the architecture you want.
Instead:
Create Worker
↓
Keep Worker Alive
↓
Image 1 → Process
Image 2 → Process
Image 3 → Process
Image 4 → Process
↓
Stop Worker
This is where Isolate.spawn() becomes more useful.
Long-Running Worker with Isolate.spawn()
Let’s create a worker capable of receiving multiple tasks.
void worker(
SendPort mainSendPort,
) {
final workerReceivePort =
ReceivePort();
mainSendPort.send(
workerReceivePort.sendPort,
);
workerReceivePort.listen(
(message) {
if (message
is Map<String, dynamic>) {
final number =
message['number'] as int;
final replyPort =
message['replyPort']
as SendPort;
final result =
number * number;
replyPort.send(result);
}
},
);
}
The worker creates its own ReceivePort.
Then it sends its SendPort back to the main isolate.
Conceptually:
Main Isolate
│
│ Spawn
▼
Worker Isolate
│
Create ReceivePort
│
Send SendPort
▼
Main Isolate
Now both sides can communicate.
Starting the Persistent Worker
Create a port:
final mainReceivePort =
ReceivePort();
Spawn:
final isolate =
await Isolate.spawn(
worker,
mainReceivePort.sendPort,
);
Receive the worker’s SendPort:
final workerSendPort =
await mainReceivePort.first
as SendPort;
Now the main isolate can send multiple tasks to the worker.
Sending Work to the Worker
Create a result port:
final resultPort =
ReceivePort();
Send:
workerSendPort.send({
'number': 25,
'replyPort':
resultPort.sendPort,
});
Receive:
final result =
await resultPort.first;
print(result);
Output:
625
Later, you can send another request without creating another worker.
final anotherResultPort =
ReceivePort();
workerSendPort.send({
'number': 50,
'replyPort':
anotherResultPort.sendPort,
});
Now the same worker processes another task.
Persistent Worker Architecture
The architecture looks like:
Worker Isolate
┌───────────────┐
Task 1 ─────► │ │ ─────► Result 1
Task 2 ─────► │ Worker │ ─────► Result 2
Task 3 ─────► │ │ ─────► Result 3
Task 4 ─────► │ │ ─────► Result 4
└───────────────┘
The isolate remains alive.
This is the key advantage of Isolate.spawn().
Lifecycle Difference
This is perhaps the most important difference.
Isolate.run()
Create
↓
Execute
↓
Return Result
↓
Exit
The lifecycle is automatically managed.
Isolate.spawn()
Create
↓
Execute
↓
Receive Messages
↓
Process
↓
Receive More Messages
↓
Process
↓
...
↓
Developer stops worker
You have much more control.
That also means more responsibility.
Killing an Isolate Created with Isolate.spawn()
Keep the returned Isolate:
final isolate =
await Isolate.spawn(
worker,
mainReceivePort.sendPort,
);
When it is no longer needed:
isolate.kill(
priority: Isolate.immediate,
);
You should also clean up ports and subscriptions where appropriate.
For example:
mainReceivePort.close();
Persistent workers should have a clear lifecycle.
Real Example: Image Processing
Suppose your application allows users to apply expensive filters to images.
Scenario A
The user selects one image:
Select Image
↓
Apply Filter
↓
Get Result
Isolate.run() may be enough:
final processed =
await Isolate.run(() {
return processImage(imageBytes);
});
Scenario B
Your application continuously processes many images:
Image 1
Image 2
Image 3
Image 4
Image 5
...
A persistent worker may make more architectural sense:
Main Isolate
│
├── Image 1 ──────►
├── Image 2 ──────► Worker Isolate
├── Image 3 ──────►
└── Image 4 ──────►
Now Isolate.spawn() becomes worth considering.
Real Example: Large JSON Processing
Suppose your application downloads a large catalog.
Flow:
API
↓
20 MB JSON
↓
Parse
↓
Transform
↓
Models
This is a one-time operation after the request.
You could use:
final products =
await Isolate.run(() {
final decoded =
jsonDecode(response.body)
as List<dynamic>;
return decoded
.map(
(item) =>
Product.fromJson(item),
)
.toList();
});
There is probably no reason to maintain a permanent worker if the operation happens occasionally.
So:
Isolate.run()
is a natural fit.
Real Example: Continuous Data Processing
Imagine an application receives data continuously and performs expensive calculations.
Data 1 ──────►
Data 2 ──────► Worker
Data 3 ──────►
Data 4 ──────►
Data 5 ──────►
Creating a new isolate for each data item may be inefficient.
A persistent worker can instead process messages continuously.
Main Isolate
│
│ Data
▼
Persistent Worker
│
│ Process
▼
Result
This is a stronger Isolate.spawn() use case.
Communication Difference
With Isolate.run():
final result =
await Isolate.run(
heavyCalculation,
);
Communication is mostly hidden.
You think in terms of:
Function
↓
Result
With Isolate.spawn():
Main
↓
SendPort
↓
Worker
↓
ReceivePort
↓
Process
↓
SendPort
↓
Main
You manage more of the messaging architecture yourself.
Error Handling with Isolate.run()
Error handling is straightforward.
try {
final result =
await Isolate.run(() {
return processData();
});
print(result);
} catch (error) {
print(
'Processing failed: $error',
);
}
The high-level API makes one-off task errors easy to work with.
Error Handling with Isolate.spawn()
With manually managed workers, you may want explicit error handling.
For example:
final errorPort =
ReceivePort();
Then:
final isolate =
await Isolate.spawn(
worker,
mainPort.sendPort,
onError: errorPort.sendPort,
);
Listen:
errorPort.listen(
(error) {
print(
'Worker error: $error',
);
},
);
You can also manage isolate exit events.
final exitPort =
ReceivePort();
Then:
isolate.addOnExitListener(
exitPort.sendPort,
);
This additional control can be useful for sophisticated worker architectures.
Performance: Isolate.run vs Isolate.spawn
A common question is:
Which one is faster?
There is no universal answer.
The bigger difference is workload structure rather than raw speed.
For one heavy task:
Create
Process
Return
Finish
Isolate.run() is simple and appropriate.
For many repeated tasks:
Create worker once
↓
Task
↓
Task
↓
Task
↓
Task
a persistent Isolate.spawn() worker can avoid repeatedly setting up a new worker architecture for every operation.
However, persistent workers consume resources while alive.
Therefore, do not keep worker isolates running without a reason.
Isolate Creation Has a Cost
Creating isolates involves overhead.
Conceptually:
Create isolate
↓
Initialize worker
↓
Transfer data
↓
Execute
↓
Transfer result
Therefore, this is usually unnecessary:
final result =
await Isolate.run(() {
return 10 + 20;
});
The calculation:
10 + 20
is dramatically cheaper than the isolate machinery surrounding it.
Isolates should be reserved for meaningful CPU workloads.
What About async/await?
Neither Isolate.run() nor Isolate.spawn() should replace normal asynchronous programming.
For example:
final response =
await http.get(url);
usually does not require another isolate.
Network I/O is already asynchronous.
The important distinction is:
I/O-bound work
↓
async/await
CPU-bound work
↓
Isolate
For example:
HTTP Request
↓
async/await
Huge JSON Parsing
↓
Potential isolate
Isolate.run vs Future()
Another common mistake is assuming this:
Future(() {
heavyCalculation();
});
moves the calculation to another isolate.
It does not.
The callback still runs on the same isolate.
Likewise:
Future<void> calculate() async {
heavyCalculation();
}
does not automatically create another isolate.
Therefore:
Future
async
await
are not replacements for isolates when the problem is CPU-bound synchronous work.
Isolate.run vs compute()
Flutter also provides:
compute()
from:
package:flutter/foundation.dart
Example:
final result =
await compute(
processData,
input,
);
For many one-off Flutter computations:
compute()
and:
Isolate.run()
serve similar high-level purposes.
A practical mental model is:
One-off Flutter helper
→ compute()
One-off Dart isolate computation
→ Isolate.run()
Persistent/custom worker
→ Isolate.spawn()
If you do not need custom communication or a persistent worker, there is usually no reason to jump immediately to Isolate.spawn().
Isolate.run vs Isolate.spawn Architecture
Consider a product application.
You download a large product catalog.
API
↓
JSON
↓
Parse
↓
Models
Use:
Isolate.run()
because it is one operation.
Now imagine an application that continuously processes incoming CPU-heavy tasks:
Task
↓
Task
↓
Task
↓
Task
↓
Task
Use a persistent worker:
Isolate.spawn()
because repeated communication is part of the architecture.
Code Complexity Comparison
Isolate.run()
final result =
await Isolate.run(() {
return processData(data);
});
Very little infrastructure is required.
Isolate.spawn()
You may need to manage:
Isolate
ReceivePort
SendPort
Messages
Subscriptions
Errors
Exit events
Cleanup
Worker lifecycle
That complexity is justified only when you actually need the additional control.
Memory and Data Transfer
Remember that Dart isolates do not simply share ordinary mutable objects.
Data is communicated between them.
Therefore, sending extremely large amounts of data can have a cost.
For example:
Main Isolate
│
│ 100 MB data
▼
Worker
│
│ 100 MB result
▼
Main
Even if processing is moved off the main isolate, data transfer can still affect overall performance.
For large binary workloads, Dart provides:
TransferableTypedData
which can be useful when transferring typed binary data between isolates.
When to Choose Isolate.run()
Choose Isolate.run() when:
- You have one CPU-heavy operation.
- The operation produces one final result.
- You do not need continuous communication.
- You do not need a persistent worker.
- You want minimal isolate-management code.
Typical examples include:
Large JSON parsing
Large sorting operation
Data aggregation
One image transformation
Compression
Encryption
Complex calculation
File parsing
Large dataset transformation
Example:
final result =
await Isolate.run(
() => processLargeDataset(data),
);
When to Choose Isolate.spawn()
Choose Isolate.spawn() when:
- The worker needs to stay alive.
- You need to send multiple tasks.
- You need two-way communication.
- You need more lifecycle control.
- You need custom error/exit handling.
- Worker startup should not happen for every repeated task.
Typical examples include:
Continuous image processing
Long-running data worker
Repeated CPU-heavy calculations
Custom worker architecture
Streaming-like processing
Persistent background computation
Conceptually:
Start Worker
↓
Task 1
↓
Task 2
↓
Task 3
↓
Task 4
↓
Stop Worker
When You Should Use Neither
This is equally important.
Suppose you are performing:
final response =
await http.get(url);
You probably do not need an isolate.
Or:
final user =
await database.getUser();
Again, normal asynchronous programming is usually enough.
Likewise:
final total =
price * quantity;
is too cheap to justify an isolate.
Therefore:
Normal API call
→ async/await
Small calculation
→ Run normally
One expensive CPU task
→ Isolate.run()
Repeated expensive CPU tasks
→ Consider Isolate.spawn()
Decision Flow
Use this decision process:
Do you have expensive work?
│
▼
Is it mostly I/O waiting?
│ │
Yes No
│ │
▼ ▼
async/await CPU-heavy?
│
Yes │
▼
Is it a one-off task?
│ │
Yes No
│ │
▼ ▼
Isolate.run() Need persistent
communication?
│
Yes
│
▼
Isolate.spawn()
This keeps isolate usage simple and intentional.
Common Mistakes
Using Isolate.spawn() for Everything
You do not need:
ReceivePort
SendPort
Isolate.spawn()
for every background computation.
If you only need:
Task
↓
Result
prefer the simpler API.
Using Isolate.run() for Tiny Calculations
Bad example:
final result =
await Isolate.run(
() => 50 * 20,
);
The isolate overhead is unnecessary.
Using Isolate.run() Repeatedly in a Hot Path
Suppose a task happens continuously:
60 times per second
Repeatedly creating one-off isolate work may not be a good design.
Consider whether:
Persistent worker
is more appropriate.
However, first ask whether the computation really belongs in Dart isolates at all.
Forgetting to Close Ports
When using Isolate.spawn():
receivePort.close();
when the port is no longer required.
Persistent resources should have clear cleanup behavior.
Forgetting to Kill Persistent Workers
Keep the isolate reference:
final isolate =
await Isolate.spawn(
worker,
sendPort,
);
Then when appropriate:
isolate.kill(
priority: Isolate.immediate,
);
Do not leave workers alive indefinitely when they no longer serve a purpose.
Frequently Asked Questions
What is the main difference between Isolate.run and Isolate.spawn?
Isolate.run() is a high-level API designed for executing a computation in another isolate and returning its result.
Isolate.spawn() gives you lower-level control and is more suitable for custom or long-running worker isolates.
Which is easier to use?
Isolate.run().
A one-off computation can often be written as:
final result =
await Isolate.run(
heavyCalculation,
);
Which should I use for JSON parsing?
For occasional CPU-heavy parsing, Isolate.run() is usually simpler.
You can also use Flutter’s compute() helper.
Which should I use for repeated calculations?
If calculations occur repeatedly and a persistent worker architecture provides a measurable benefit, Isolate.spawn() may be more appropriate.
Does Isolate.run automatically close the worker?
Yes. It is designed around running the computation, returning its result, and managing the temporary worker lifecycle for you.
Can Isolate.spawn return a result?
Yes, but you generally implement communication explicitly using mechanisms such as SendPort and ReceivePort.
Is Isolate.spawn faster than Isolate.run?
Not automatically.
Performance depends on workload size, communication, isolate creation, data transfer, frequency, and platform behavior.
The main distinction is control and lifecycle rather than simply “fast vs slow.”
Should API calls use Isolate.run?
Usually no.
Network requests are I/O-bound and work naturally with async/await.
CPU-heavy processing performed after receiving the response may be an isolate candidate.
Final Comparison
| Requirement | Recommended Approach |
|---|---|
| HTTP/API request | async/await |
| Database request | async/await |
| Tiny calculation | Normal function |
| One expensive calculation | Isolate.run() |
| Large one-time JSON parsing | Isolate.run() or compute() |
| One-time large data transformation | Isolate.run() |
| Repeated CPU-heavy tasks | Consider Isolate.spawn() |
| Persistent worker | Isolate.spawn() |
| Two-way worker communication | Isolate.spawn() + ports |
| Custom isolate lifecycle | Isolate.spawn() |
Final Thoughts
Isolate.run() and Isolate.spawn() both allow Dart applications to move suitable CPU-intensive work away from the main isolate, but they operate at different levels of abstraction.
The easiest rule to remember is:
Isolate.run()
↓
Run one task
↓
Get one result
↓
Worker finishes
while:
Isolate.spawn()
↓
Create worker
↓
Communicate using messages
↓
Process multiple tasks
↓
Keep worker alive if needed
↓
Stop worker manually
For most one-off CPU-heavy tasks, start with:
final result =
await Isolate.run(
heavyCalculation,
);
It keeps the implementation simple and avoids manually managing ports and worker lifecycle.
Move to:
Isolate.spawn()
when your requirements genuinely involve persistent workers, repeated communication, custom lifecycle management, or more advanced isolate architectures.
Most importantly, do not use either API simply because a function is asynchronous.
Use:
async/await
for normal I/O-bound work, and consider isolates when CPU-bound synchronous work is large enough to affect the responsiveness of your application.
That distinction will help you choose between async/await, Isolate.run(), and Isolate.spawn() correctly in real Dart and Flutter applications.
