SDWebImage: the Objective-C image pipeline that still anchors iOS caching

The problem SDWebImage solves: remote images without a hand-rolled cache

Any app that shows a scrolling list of remote images runs into the same three problems. The first is that the same URL appears in several cells at once, and naive code fires several downloads for one image. The second is that decoding a full-size JPEG on the main thread drops frames. The third is that without a cache, every scroll back up re-downloads what the user already saw.

SDWebImage exists to absorb all three. The README describes it as an asynchronous image downloader with cache support, plus categories on UI elements such as UIImageView, UIButton and MKAnnotationView so that a view can be handed a URL directly. The stated guarantees are worth reading literally: the same URL will not be downloaded several times, bogus URLs will not be retried again and again, and the main thread will never be blocked. Those three sentences describe the contract the library is built around, and they are the reason it has stayed in UIKit projects rather than being replaced by a small helper class.

The audience is narrower than the topic list suggests. This is an Objective-C library first, with Swift support layered on top. If your interface is SwiftUI, the README points to a separate framework, SDWebImageSwiftUI, built on the core caching, loading and animation functions. If your app is pure SwiftUI with no UIKit anywhere, the core library is still the engine but not the API you will write against.

One naming note that trips people up: SD is the prefix for Simple Design, the team name at Daily Motion for the author Olivier Poitrey. It is not an abbreviation of the library's own name.

How the download, decode and cache layers fit together

The architecture is deliberately split into layers that can each be replaced. At the top, the view categories take a URL and a placeholder, then hand the work down. Below that sits a loader, and below that a downloader that performs the network request. The result passes through a coder that turns bytes into an image, and then into a cache that stores it twice: in memory for immediate reuse and on disk for the next launch.

The README lists the pieces that make this more than a thin wrapper. Background image decompression happens off the main thread to avoid frame rate drops, which matters because decoding is often the expensive part rather than the transfer. Progressive loading is supported, including for animated images, so a partially received image can be shown as it arrives. Thumbnail decoding exists specifically to save CPU and memory on large images. Transformations can be applied to an image right after download, which is where you would crop or resize before the result reaches the cache.

The extension points are the part that shapes long-term maintenance. Both the cache system and the loader system are described as customizable and multiple, meaning you can run more than one of each. Coders are pluggable so that formats Apple does not handle natively can be added. The README names the Photos Library plugin as an example of a custom loader, which is a useful illustration: the same pipeline that fetches over HTTP can be pointed at a local asset library.

That modularity is also why the project moved parts of itself out. The README states that during the 5.0 refactoring the library was modularized, with new modules living in the SDWebImage org rather than in the core repository. The core stays focused; the ecosystem carries the rest. The practical consequence is that a feature you remember from an older version may now be a separate repository with its own release cadence.

Installing SDWebImage with CocoaPods, Carthage or Swift Package Manager

The repository ships a podspec, a Package.swift and Carthage compatibility, so the install path depends on what your project already uses. The README does not print a CocoaPods pod line in the text available here, so the safest approach is to add the dependency through the tool's own mechanism and let it resolve the version. The pod is registered under the name SDWebImage.

For Swift Package Manager, the Package.swift file at the repository root is the manifest, and the same manifest is what supports visionOS. The README states that from 5.19 onward SDWebImage supports visionOS across all package managers, and that for 5.18 the library could be compiled for visionOS but was still in beta with possible issues. If you target visionOS, check the version you resolve rather than assuming the newest tag is what your lockfile picked.

Once the dependency is in place, the first real use is a UIImageView category call. The README gives the categories as the convenience layer, so the shape of the call is a URL and a placeholder passed to the view. The README's own example uses a placeholder image and a URL, and the wiki page linked from the feature list is titled How to use.

What you should see is the placeholder immediately, then the remote image once the download and decode finish. Reusing the same URL in another cell should not produce a second network request, which is the deduplication guarantee in practice.

For SwiftUI, the core library is not the API surface. The README directs SwiftUI users to SDWebImageSwiftUI, a separate framework built on the core caching, loading and animation functions. If you install only SDWebImage and then look for a SwiftUI view, you will not find one in the core module.

Animated formats are opt-in, and that surprises new users

The most concrete limitation in the README is about animated images, and it is easy to miss. Static images fall back to Apple's built-in decoders, so JPEG, PNG, TIFF and BMP work without configuration. Animated images do not follow the same rule. The README states that as of the 5.19.x line, only traditional animated formats such as GIF and APNG are registered by default, and that modern formats including AWebP, HEICS and AVIF are not, even on the latest firmware.

So an app that displays an animated WebP will show a static frame, not an animation, unless the developer registers the coder. The README frames this as a deliberate interim state and says the project intends to change the behaviour in future by always registering all of Apple's built-in animated formats. Until that ships, the registration is the developer's job, described as a one-line change with details in the WebP Coder and HEIC Coder wiki pages.

Deployment targets add a second constraint. WebP through SDWebImageAWebPCoder requires iOS 14 or macOS 11.0, and older firmware needs the SDWebImageWebPCoder plugin instead. HEIC covers iOS 11 and macOS 10.13, with animated HEIC from iOS 13 and macOS 10.15, and lower firmware needs SDWebImageHEIFCoder. JPEG-XL is built in from iOS 17 and macOS 14.0, with SDWebImageJPEGXLCoder for anything older. Each of those is a different dependency with its own version history.

This is the case where SDWebImage is the wrong tool for a small job. If your app shows a handful of static images and you already have a working URLSession call with an NSCache in front of it, the coder plugin system and the modular ecosystem are overhead you will pay for without using.

SDWebImage vs Kingfisher vs AsyncImage: different layers, not just different brands

The comparison people search for is usually framed as SDWebImage versus Kingfisher, and the difference that matters is not features but language and API shape. SDWebImage is an Objective-C library with Swift support and categories on UIKit views. Kingfisher is written in Swift and exposes a Swift-native API. In a Swift codebase that has no Objective-C heritage, Kingfisher reads more naturally; in a mixed or older codebase, SDWebImage's categories drop into existing view code without a rewrite.

The more interesting comparison is with SwiftUI's own AsyncImage. AsyncImage handles the download and display of a single image with no cache layer you control, no disk persistence and no deduplication across views. SDWebImage's core is precisely the opposite: a memory plus disk cache with automatic expiration, and a guarantee that the same URL is not fetched repeatedly. If your list recycles views and users scroll back and forth, that difference is the whole point. If you render one image once on a detail screen, AsyncImage is less machinery.

SDWebImageSwiftUI is the middle option: it keeps the SDWebImage caching and loading engine but presents it as a SwiftUI view, so you are not choosing between a cache and a SwiftUI-friendly API. The README describes it as built on top of the core caching, loading and animation functions rather than as a reimplementation.

One thing the README does not do is compare itself to alternatives or publish migration guides between them. Any claim about relative speed between these libraries would need your own measurement; nothing in the repository material supports one.

Maintenance, releases and what the MIT licence means for shipping

The last push to the default branch was on 2026-04-15. The most recent release listed is 5.21.7 on 2026-02-26, following 5.21.6 on 2026-02-06 and 5.21.5 on 2025-12-03. The pattern is a steady stream of patch releases with occasional minor versions, which is what you want from a dependency that sits under your UI: small, frequent changes rather than large migrations.

The upgrade cost is concentrated in two places. The first is the coder plugins, which live in separate repositories and version independently of the core. Upgrading SDWebImage does not automatically upgrade SDWebImageWebPCoder or SDWebImageHEIFCoder, so a format that works today can break if you move one and not the other. The second is the 5.x modularization described in the README: features that once lived in the core now live in the SDWebImage org, so a major version bump can move code out from under you.

The licence is MIT. That is permissive, and it is a different licence from what the README's badge links to, which points at Apache 2.0. The repository's LICENSE file and the stated licence for this project are MIT; treat the badge as a display artifact rather than the governing text. MIT permits use in closed-source applications with attribution, but the exact obligations depend on your distribution model and jurisdiction, so read the LICENSE file rather than a summary.

Editorial conclusion

Adopt SDWebImage if you maintain a UIKit app with many remote images, need a shared memory and disk cache, and want download deduplication and background decompression without writing that plumbing yourself. Do not adopt it expecting animated WebP or HEIC to work out of the box: the README states that only GIF and APNG animated coders are registered by default, so you must register AWebP or HEIC yourself. Before committing, verify three things in your own project: that your deployment target matches the coder you need (WebP through SDWebImageAWebPCoder requires iOS 14 or macOS 11.0, HEIC requires iOS 11 or macOS 10.13), that your package manager version supports visionOS if you target it (5.19 or later), and that the SDWebImageSwiftUI wrapper is the right layer if your views are SwiftUI rather than UIKit.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. SDWebImage/SDWebImage on GitHub