Post cover image
Figure 1. Golden rule: The Repository owns the thread decision

March 18, 2026

Coroutine Dispatchers in Android: The Complete Guide

Every Android developer using coroutines has been here: you open a Repository, stare at a suspend fun, and wonder — do I need…

By Sergey Nes

6 min read

Every Android developer using coroutines has been here: you open a Repository, stare at a suspend fun, and wonder, do I need withContext(Dispatchers.IO) here or not? You add it "just to be safe." Six months later a colleague removes it "because DataStore already handles threading." Your CI doesn't catch it. Your users don't feel it. But the confusion compounds.

This article kills that confusion for good.

What Is a Dispatcher?

A CoroutineDispatcher determines which thread (or thread pool) a coroutine runs on. Kotlin coroutines are not threads, they are lightweight, suspendable units of work. A dispatcher is the bridge between a coroutine and the underlying threads.

There are four built-in dispatchers:

None

The key insight: IO and Default share the same thread pool internally (since Kotlin 1.6), but they have different concurrency limits. Dispatchers.IO is elastic, it can spin up to 64 threads to handle blocking calls. Dispatchers.Default is bounded to the number of CPU cores to avoid thrashing.

The MVVM Contract: Who Owns the Thread Decision?

This is the single most important rule in this article:

The Repository owns the thread decision. The ViewModel and UI never should.

Here is why. The ViewModel calls the Repository. If the ViewModel has to know whether getData() runs on IO or Default, it has leaked an implementation detail upward. The ViewModel now needs to change if you swap Room for a file-based cache. That's a coupling violation.

// ✅ Correct — ViewModel is thread-agnostic
fun loadUser(id: String) = viewModelScope.launch {
    // whoever calls this doesn't care about threads
    val user = userRepository.getUser(id)
    _uiState.value = UiState.Success(user)
}
// ❌ Wrong — ViewModel knows too much
fun loadUser(id: String) = viewModelScope.launch(Dispatchers.IO) {
    val user = userRepository.getUser(id)
    withContext(Dispatchers.Main) {
        // StateFlow is thread-safe — this switch is unnecessary
        _uiState.value = UiState.Success(user)
    }
}

The second version works, but it breaks the contract. The ViewModel now:

  • Assumes getUser() is blocking (what if it moves to an in-memory cache?)
  • Manually switches back to Main to update state (StateFlow is thread-safe, you don't need to)
  • Is harder to test (you need a TestDispatcher injected at the ViewModel level too)

The Already-Main-Safe APIs — Know Them by Heart

Several widely-used Android libraries implement main-safety internally. Calling them from the main thread is intentional and safe:

Room

Room's suspend functions and Flow queries run on Dispatchers.IO internally. If you wrap them:

// ❌ Double-wrapping — redundant
suspend fun getUsers(): List<User> = withContext(Dispatchers.IO) {
    userDao.getAllUsers() // Room already dispatches to IO
}

// ✅ Correct
suspend fun getUsers(): List<User> = userDao.getAllUsers()

Gotcha: Only suspend Room functions are main-safe. If you write a @Transaction function that is not suspend, it runs on the calling thread and will block Main if called from there. Always make @Transaction functions suspend.

// ❌ Not main-safe — blocks the calling thread
@Transaction
fun transferFunds(from: Account, to: Account) { ... }

// ✅ Main-safe
@Transaction
suspend fun transferFunds(from: Account, to: Account) { ... }

DataStore (Preferences and Proto)

Both DataStore.data (a Flow) and DataStore.edit {} use Dispatchers.IO internally, this is documented explicitly in the Jetpack source. Wrapping them in withContext(Dispatchers.IO) is noise.

// ❌ Redundant
suspend fun getTheme(): Theme = withContext(Dispatchers.IO) {
    dataStore.data.map { it.theme }.first()
}

// ✅ Correct
suspend fun getTheme(): Theme = dataStore.data.map { it.theme }.first()

// ✅ Also correct
suspend fun saveTheme(theme: Theme) {
    dataStore.edit { it.theme = theme }
}

Retrofit with suspend functions

When you declare a Retrofit interface method as suspend, Retrofit uses Dispatchers.IO under the hood via OkHttp's async dispatch. No thread-switching needed on your side.

// ✅ Correct — Retrofit handles threading
suspend fun getUser(id: String): User = apiService.fetchUser(id)

What is NOT main-safe

// ❌ These block the calling thread — you must use withContext
suspend fun readFile(): String = withContext(Dispatchers.IO) {
    File(path).readText()
}

suspend fun writeToSocket(data: ByteArray) = withContext(Dispatchers.IO) {
    socket.getOutputStream().write(data)
}

suspend fun sortAndDiff(items: List<Item>): List<Item> =
withContext(Dispatchers.Default) {
    items.sortedBy { it.timestamp }.distinctBy { it.id }
}

Anti-Patterns in the Wild

1. Defensive wrapping of already-main-safe APIs

// Seen in real codebases
suspend fun saveSettings(settings: Settings) = withContext(Dispatchers.IO) {
    dataStore.edit { prefs ->            // DataStore already uses IO
        prefs[KEY_THEME] = settings.theme
        prefs[KEY_FONT_SIZE] = settings.fontSize
    }
}

This isn't "being safe." It's misleading, a reader assumes the withContext is load-bearing. It also makes it harder to spot real missing thread switches elsewhere.

2. Using Dispatchers.IO for CPU work

// ❌ Wrong dispatcher for the job
suspend fun processImages(images: List<Bitmap>): List<Bitmap>
 = withContext(Dispatchers.IO) {
    images.map { applyFilter(it) } // CPU-bound, not I/O-bound
 }

Dispatchers.IO can spawn 64 threads. Saturating them with CPU work starves actual I/O operations. Use Dispatchers.Default for CPU-bound work, it limits concurrency to the number of cores, which is exactly what the CPU scheduler wants.

3. Launching with a dispatcher in viewModelScope for ordinary work

// ❌ Unnecessary
fun loadFeed() = viewModelScope.launch(Dispatchers.IO) {
    val items = feedRepository.getFeed() // already main-safe inside
    _feedState.value = items             // StateFlow.value is thread-safe
}

viewModelScope defaults to Dispatchers.Main.immediate. That's correct for a ViewModel. The Repository call suspends without blocking Main. StateFlow.value is thread-safe from any thread. There is no reason to switch dispatchers here.

4. Forgetting to switch threads for truly blocking calls

// ❌ This WILL block the main thread
suspend fun readConfig(): Config {
    val json = File(configPath).readText() // no withContext!
    return Json.decodeFromString(json)
}

// ✅ Fixed — Now main-safe and appropriately dispatched
suspend fun readConfig(): Config = withContext(Dispatchers.IO) {
    // Now safe to call from Main
    val json = File(configPath).readText()
    // Also happens off the Main thread
    Json.decodeFromString<Config>(json)
}

This is the opposite mistake, assuming everything is already safe. Legacy Java I/O, custom file access, OkHttp's synchronous .execute(), and blocking SDK calls all require an explicit withContext(Dispatchers.IO).

Advanced: limitedParallelism

Since Kotlin 1.6, you can carve out a sub-pool from Dispatchers.IO with a custom concurrency limit:

// Create a dispatcher that allows max 4 concurrent operations
private val limitedIO = Dispatchers.IO.limitedParallelism(4)

suspend fun uploadFile(file: File) = withContext(limitedIO) {
    storageService.upload(file)
}

This is useful when:

  • You're calling a backend that rate-limits concurrent connections
  • You're writing to a shared resource (database migration, cache rebuild)
  • You want to prevent one heavy background task from saturating the IO pool

Inject Dispatchers for Testability

Hardcoded dispatchers make coroutine testing fragile. The standard solution is to inject a CoroutineDispatcher (or a CoroutineDispatcherProvider) and swap it with a TestDispatcher in tests.

// Production
class UserRepository(
    private val dao: UserDao,
    private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO
) {
    suspend fun getUsers(): List<User> = withContext(ioDispatcher) {
        dao.getAllUsers()
    }
}
// Test
@Test
fun `getUsers returns list from dao`() = runTest {
    val testDispatcher = StandardTestDispatcher(testScheduler)
    val repo = UserRepository(fakeDao, ioDispatcher = testDispatcher)

    val users = repo.getUsers()

    assertThat(users).isEqualTo(fakeDao.users)
}

Using StandardTestDispatcher gives you full control over time and coroutine scheduling. UnconfinedTestDispatcher runs coroutines eagerly, useful for simple assertion tests where you don't need to control execution order.

Dispatchers Beyond MVVM — Other Common Contexts

Jetpack Compose

LaunchedEffect and rememberCoroutineScope both default to the main dispatcher. The same rules apply: call main-safe Repository functions directly, use withContext inside if you need a thread switch.

LaunchedEffect(userId) {
    // Fine — repository is main-safe
    val user = userRepository.getUser(userId)
    userName = user.name
}

WorkManager with CoroutineWorker

CoroutineWorker.doWork() already runs on Dispatchers.Default. Don't double-wrap with it, but do use withContext(Dispatchers.IO) for disk/network work inside doWork().

class SyncWorker(ctx: Context, params: WorkerParameters) :
CoroutineWorker(ctx, params) {
    override suspend fun doWork(): Result {
        // runs on Dispatchers.Default
        return withContext(Dispatchers.IO) { // switch for I/O
            val data = api.fetchSync()
            db.insertAll(data)
            Result.success()
        }
    }
}

BroadcastReceiver with goAsync()

BroadcastReceiver.onReceive() runs on the main thread with a hard 10-second deadline. Use goAsync() + a coroutine scope to do background work:

class NetworkReceiver : BroadcastReceiver() {
    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)

    override fun onReceive(context: Context, intent: Intent) {
        val pendingResult = goAsync()
        scope.launch {
            withContext(Dispatchers.IO) {
                // do background work
            }
            pendingResult.finish()
        }
    }
}

The Decision Framework — Quick Recap

In the ViewModel:

  • Use viewModelScope.launch { } with no dispatcher argument
  • Only add Dispatchers.Default if you have heavy CPU logic that truly belongs in the ViewModel (rare)
  • Never manually switch back to Main after a suspend call, StateFlow and LiveData are thread-safe

In the Repository:

  • Room, DataStore, Retrofit suspend → call directly, no withContext
  • File I/O, sockets, legacy blocking APIs → withContext(Dispatchers.IO)
  • Sorting, diffing, parsing, image processing → withContext(Dispatchers.Default)
  • Rate-limited or resource-constrained I/O → withContext(Dispatchers.IO.limitedParallelism(n))

Everywhere:

  • Inject dispatchers as constructor parameters, hardcoded dispatchers are an obstacle for testing
  • If a library has coroutine support, read its docs once to confirm main-safety before adding withContext
None None

Coroutine Dispatchers in MVVM — Quick Reference

None

Rule of thumb: if the Android library ships with coroutine support, it is almost certainly already main-safe. Read the docs once; stop adding defensive withContext everywhere.

Closing Thought

Dispatcher mistakes rarely crash your app. They silently degrade I, blocked UI threads, over-subscribed IO pools, misleading code that future developers cargo-cult into the wrong places. The discipline of knowing which layer owns the thread decision and which APIs are already main-safe is what separates maintainable coroutine code from accidental coroutine code.

Read the docs to know your APIs, respect your layers, and let the dispatchers do their job.

Follow me here on Medium and on LinkedIn for updates, and feel free to reach out if you need help with native mobile development or rescuing an Android or iOS project from Vibe-coding.