Animated WebP is not registered by default; you register the coder yourself

An animated WebP renders as nothing until you add one line of code

There is a note in the README addressed to new users, and it contains the most consequential behaviour in the library.

The library uses a coder plugin system to support both the formats Apple's operating system can decode and external ones. For static images, the built-in system decoder is always used as a fallback. For animated images, that fallback does not apply. As of the five-point-one-nine line, only the traditional animated formats, GIF and APNG, are registered by default. The modern formats, animated WebP, animated HEIC and AVIF, are not, and the note is explicit that this is the case even on the latest firmware.

The fix is documented as registering the coder yourself with one line of code, and there are wiki pages for the WebP and HEIC coders. The project also says it intends to change this behaviour and always register all of the built-in animated formats, to make it easier for a new user.

Until that lands, the practical rule is that the formats listed as supported are supported by the system, not necessarily registered by this library, and the difference is exactly the animated ones.

The last feature bullet is one word and an exclamation mark

The feature list is formatted as a checklist, which is a slightly odd choice for a README and turns out to be worth reading literally.

Most of the items make a specific, checkable claim. There are categories for the image view, button and map annotation view. There is an asynchronous downloader. There is a two-tier cache, memory and disk, with automatic expiration. There is decompression on a background thread to avoid dropping frames, thumbnail decoding to save processor and memory on large images, progressive loading, composable transformations applied after download, configurable caches, configurable loaders, loading indicators, and transition animations.

Then three items that are guarantees rather than features: that the same URL will not be downloaded several times, that a bad URL will not be retried endlessly, and that the main thread will never be blocked. Those are the three an adopter should care about most, and they are the three most likely to be assumed rather than tested.

The final item in the list is the word Performances, with an exclamation mark, and nothing else. No number, no benchmark, no comparison.

That is either a placeholder someone left behind, or a deliberate refusal to quote a figure. Either way it tells you where to look for a decision: not at this list, which contains a performance claim that is only a word, but at the two-tier cache design, the background decompression and the thumbnail decoding path, which are the mechanisms the performance would come from. If performance is your criterion, measure it on your own content, and note that your content is mostly animated modern-format images if that is what your users see.

Format support has six version floors and four separate packages

The supported formats section is the densest part of this README, and the reason is that format support in this library is a function of the operating system version, with a plugin for everything below it.

The formats the system decodes are listed with their floors. HEIC arrives at a particular iOS and macOS version, and animated HEIC arrives two versions later. WebP has its own floor, and again a later floor for the animated variant. JPEG-XL has the newest floor of the three, and is built into the system at that version. Below each floor, the answer is a different package.

The packages are named after the format and the platform generation, and there are several. There is a WebP coder based on a browser engine's image library, a HEIF coder based on a standalone image library, a BPG coder based on another, and a JPEG-XL coder. The WebP and HEIF coders list iOS 9+/macOS 10.11+, lower than the system floors, because they are based on libwebp and libheif.

So the arithmetic a user does is: for each format you serve, and for the oldest OS your app supports, either the system can decode it or you add a package, and for the animated variants you add a registration call on top of that.

That is a real ongoing cost rather than a one-time setup, and it is invisible until a customer on an old device sees a blank. The one saving grace is that the project has kept these as separate packages rather than folding decoders into the core, so the cost is only paid for formats you actually use.

SwiftUI is a separate framework with a higher deployment floor than the core

The feature list says modern Objective-C and better Swift support, and that phrase does less work than it appears to.

The SwiftUI story is a separate framework in a separate repository, built on top of the core's caching, loading and animation functions. It introduces two view types for SwiftUI, an image indicator modifier that works on any view, and an observable object for data sources. The core categories for the image view, the button and the map annotation view remain the UIKit path.

The two paths have different deployment floors, and that is the part to check. The SwiftUI framework is stated as supporting a later iOS and macOS minimum, a later tvOS minimum, a later watchOS minimum, and a specific Swift version. The core, meanwhile, supports formats from an earlier iOS and macOS generation, and the plugins go back further still.

So a project that has to run on an older operating system can use the core, or one of the low-floor coder plugins, but not the SwiftUI framework. That is a real constraint for anyone whose user base is not modern, and it is the kind of thing that only surfaces when you try to adopt the framework and the build refuses.

The modularisation was deliberate. The README says the library was refocused at version five to keep the core limited to core features and to move or build new modules in the wider organisation instead, on the reasoning that extensibility and the ability to have custom behaviours should not make the core heavier.

visionOS is beta, and on it only the standard Xcode integration is supported

The platform section is three paragraphs and the second one contains the caveat.

From a recent version onwards, the library supports visionOS across all of the package managers, including CocoaPods, Carthage and the Swift package manager, and it tells you to upgrade the related tools if you hit problems. Before that version, the platform could be compiled for, but the note is explicit that it is still in beta and may contain issues unlike the stable interface kit support, and that issues are welcome.

Then the sentence that should stop a reader: to build on visionOS, only the standard Xcode integration is supported.

So there are two claims sitting together. VisionOS support is described as available across all package managers, and the build route for that platform is described as the Xcode integration only. If your build system is a package manager rather than an Xcode project, the two statements cannot both apply to you, and the practical reading is that the package-manager paths are not the supported route on that platform even though they are listed.

The example applications in the repository tell the same story from the other direction. There are demo applications for the phone platforms, for macOS, for the television, for the watch, and one for a headset. So the platform has a demo, which is more than most libraries with beta support have, and the demo is the fastest way to find out what actually works.

The licence badge points at Apache 2.0 while the project is MIT

A small inconsistency that takes ten seconds to notice and is worth resolving before you paste this into a compliance review.

One of the badges at the top of the README links to the Apache License version 2.0 text. The repository's declared licence is the MIT licence, and there is a licence file in the root of the tree.

So the badge and the declared licence disagree. One of them is wrong, and the practical point is that the badge is the one most people copy into a slide, and it is the one that is not derived from the repository's own metadata.

The fix is trivial and the reason to mention it is that there is a licence file in the repository, so the authoritative answer is a file read away and there is no need to guess from a badge. If your organisation tracks licences by scanning dependency manifests, you are probably getting the right answer already, because the manifest is what the scanner reads. If a human copied the badge, they have the wrong one.

The rest of the badge row is a better guide to what this project is than the feature list is. There is a continuous integration badge, two links to generated documentation, a package-manager badge, a coverage badge, and a link to Apple's developer documentation on making a Mac version of an iPad application, which is an odd thing to badge in a library but a fair signal that Mac support is a first-class target rather than an accident.

Four distribution paths, five demo apps, and a library layer split off from the UIKit one

The repository offers four ways to consume it and five example applications, and the tree shows one more structural decision.

The four paths are a CocoaPods specification, a Swift package manifest, a configuration directory for the Swift package manager, and an Xcode project with a workspace beside it. The README's own note for the newest platform says the Xcode integration is the supported build route there, and points readers to the Swift package manager and manual installation sections, so all four are live.

The example applications are separate projects, one for the phone platforms, one for macOS, one for the television, one for the watch plus its extension, and one for a headset, alongside a directory of custom path examples and a packages example. A library that ships one example per platform is telling you that its behaviour differs per platform, which for an image library it does, because the whole format story is operating-system-version dependent.

The structural decision is in the top-level directories. There is a directory for the library itself, a separate one for the map kit category, and a separate one named WebImage. The map kit one is the same split you would expect from the feature list, which names the map annotation view among its categories.

There is also a certificates directory, a scripts directory, a configuration directory, and an SDWebImage.json file at the root.

Editorial conclusion

SDWebImage fits an iOS team that wants a battle-tested cache and loader with UIKit categories, and that accepts registering the coders its content actually needs. It does not fit a SwiftUI project on an older deployment target, because the SwiftUI framework has a higher floor than the core, and it does not fit anyone who expects modern animated image formats to work out of the box. Verify first which of your content is animated and which formats it uses, register the coders for those, and then check the actual licence file rather than the badge.

Frequently asked questions

Official sources

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