How to use SDWebImage: install, cache and load images on iOS

What SDWebImage does and who it is for

SDWebImage provides an async image downloader with cache support. For convenience, it adds categories to UI elements like UIImageView, UIButton and MKAnnotationView, so your app can show a web image without writing the download and cache logic yourself.

The library is aimed at iOS or macOS app developers who need to show remote images in lists or grids, and at teams that want caching, progressive loading and image transformations handled by a tested library. It is not aimed at Android, web browser or other non-Apple projects.

• Downloads images asynchronously and caches them in memory and on disk
• Adds image loading helpers to UIImageView, UIButton and MKAnnotationView
• Supports animated images such as GIF and APNG
• Offers a SwiftUI module, SDWebImageSwiftUI, built on the same core

What you need before you install SDWebImage

The README lists Xcode and one of Swift Package Manager, CocoaPods or Carthage as prerequisites. Integration assumes you are already comfortable with Apple-platform app development, so a beginner with no Xcode experience will likely need to learn the basics first.

The README also notes that SDWebImage supports Mac Catalyst and, from a recent release, visionOS through all package managers. The visionOS support is described as beta for earlier releases, so check the README before relying on it.

• Xcode
• Swift Package Manager, CocoaPods or Carthage
• Basic familiarity with building iOS or macOS apps

Install SDWebImage with a package manager

The source material gives a clone command so you can inspect the repository and its README locally. Clone it with the command below.

The README has dedicated sections for installing with Swift Package Manager and a manual installation guide. Follow the section that matches the package manager your project already uses. The README sections on these installation paths were not included in the source text used for this page, so read them directly in the repository for exact setup steps.

Load your first web image into a UIImageView

Once the library is in your project, the core idea is that UIImageView gets helper methods for loading a web image. You give it a URL and the library handles downloading, caching and displaying the result. The README describes these categories but the source text used here does not include the exact method names, so take the call signature from the SDWebImage wiki or the header files in the repository.

Because the library keeps images in memory and on disk, a URL that has already been loaded does not need to be downloaded again. The README also states that the same URL will not be downloaded several times and that bogus URLs will not be retried repeatedly.

• Use the UIImageView category to set a remote image from a URL
• Rely on the built-in cache so repeated images load without a new download
• Expect failed or invalid URLs to be handled without endless retries

Use caching, progressive loading and transformations

The README lists several features beyond basic loading. These include automatic cache expiration handling, background image decompression to avoid frame rate drops, progressive image loading, thumbnail decoding for large images, and transformations that can be applied right after download.

Each of these has its own section in the project wiki under Advanced Usage. Read those sections when you need to tune memory use or change how images appear while loading.

• Automatic cache expiration handling for memory and disk caches
• Background decompression to avoid frame rate drops
• Progressive loading, including animated images
• Thumbnail decoding to save CPU and memory for large images
• Customizable and composable transformations applied after download
• Image loading indicators and transition animations

Handle animated and newer image formats

SDWebImage supports Apple's built-in formats such as JPEG, PNG, TIFF and BMP, plus GIF and APNG animations. The README says that by default it registers only traditional animated formats like GIF and APNG. Modern animated formats such as animated WebP and HEIC must be registered manually, using one line of code per format as described in the WebP Coder and HEIC Coder sections of the wiki.

For formats beyond the built-in set, the README points to coder plugins such as SDWebImageWebPCoder, SDWebImageAVIFCoder and SDWebImageSVGCoder.

• Built in: JPEG, PNG, TIFF, BMP, GIF and APNG animation
• Register manually: animated WebP, HEIC and AVIF
• Plugins exist for WebP, HEIF, AVIF, PDF, SVG, Lottie and JPEG-XL