Migrating from Coil 2.x to Coil 3.x in Jetpack Compose: Complete Migration Guide

This guide helps you move from Coil 2.x to Coil 3.x in Jetpack Compose apps. It explains the key differences between versions, shows step-by-step how to migrate, and shares best practices for using SubcomposeAsyncImage The right way.

Understanding Coil Versions

What is Coil 2.x?

Coil 2.x was the last stable version before Coil 3. It was made specifically for Android and worked well with Jetpack Compose. Key features included:

• Android-only support
• Kotlin Coroutines for async image loading
• Jetpack Compose tools like AsyncImage and rememberImagePainter
• Built-in networking with OkHttp
• Image formats supported: JPEG, PNG, WebP, GIF, SVG, video frames
• Memory caching with basic pooling
• Image transformations built-in
• Used Android Context directly
• Versions ranged from 2.0.0 to 2.6.0

What is Coil 3.x?

Coil 3.x is a big upgrade with support for Kotlin Multiplatform (Android, iOS, Desktop, Web). Key improvements include: