Swiftpack.co - Package - SDWebImage/SDWebImage

Build Status Pod Version Pod Platform Pod License Carthage compatible SwiftPM compatible Mac Catalyst compatible codecov

This library provides an async image downloader with cache support. For convenience, we added categories for UI elements like UIImageView, UIButton, MKAnnotationView.


Supported Image Formats

  • Image formats supported by Apple system (JPEG, PNG, TIFF, BMP, ...), including GIF/APNG animated image
  • HEIC format from iOS 11/macOS 10.13, including animated HEIC from iOS 13/macOS 10.15 via SDWebImageHEICCoder. For lower firmware, use coder plugin SDWebImageHEIFCoder
  • WebP format from iOS 14/macOS 11.0 via SDWebImageAWebPCoder. For lower firmware, use coder plugin SDWebImageWebPCoder
  • Support extendable coder plugins for new image formats like BPG, AVIF. And vector format like PDF, SVG. See all the list in Image coder plugin List

Additional modules and Ecosystem

In order to keep SDWebImage focused and limited to the core features, but also allow extensibility and custom behaviors, during the 5.0 refactoring we focused on modularizing the library. As such, we have moved/built new modules to SDWebImage org.


SwiftUI is an innovative UI framework written in Swift to build user interfaces across all Apple platforms.

We support SwiftUI by building a brand new framework called SDWebImageSwiftUI, which is built on top of SDWebImage core functions (caching, loading and animation).

The new framework introduce two View structs WebImage and AnimatedImage for SwiftUI world, ImageIndicator modifier for any View, ImageManager observable object for data source. Supports iOS 13+/macOS 10.15+/tvOS 13+/watchOS 6+ and Swift 5.1. Have a nice try and provide feedback!

Coders for additional image formats

Custom Caches

Custom Loaders

  • SDWebImagePhotosPlugin - plugin to support loading images from Photos (using Photos.framework)
  • SDWebImageLinkPlugin - plugin to support loading images from rich link url, as well as LPLinkView (using LinkPresentation.framework)

Integration with 3rd party libraries

Community driven popular libraries

  • FirebaseUI - Firebase Storage binding for query images, based on SDWebImage loader system
  • react-native-fast-image - React Native fast image component, based on SDWebImage Animated Image solution
  • flutter_image_compress - Flutter compresses image plugin, based on SDWebImage WebP coder plugin

Make our lives easier

You can use those directly, or create similar components of your own, by using the customizable architecture of SDWebImage.


  • iOS 9.0 or later
  • tvOS 9.0 or later
  • watchOS 2.0 or later
  • macOS 10.11 or later (10.15 for Catalyst)
  • Xcode 11.0 or later

Backwards compatibility

Getting Started

Who Uses It


  • If you need help, use Stack Overflow. (Tag 'sdwebimage')
  • If you'd like to ask a general question, use Stack Overflow.
  • If you found a bug, open an issue.
  • If you have a feature request, open an issue.
  • If you need IRC channel, use Gitter.


How To Use

  • Objective-C
#import <SDWebImage/SDWebImage.h>
[imageView sd_setImageWithURL:[NSURL URLWithString:@"http://www.domain.com/path/to/image.jpg"]
             placeholderImage:[UIImage imageNamed:@"placeholder.png"]];
  • Swift
import SDWebImage

imageView.sd_setImage(with: URL(string: "http://www.domain.com/path/to/image.jpg"), placeholderImage: UIImage(named: "placeholder.png"))

Animated Images (GIF) support

In 5.0, we introduced a brand new mechanism for supporting animated images. This includes animated image loading, rendering, decoding, and also supports customizations (for advanced users).

This animated image solution is available for iOS/tvOS/macOS. The SDAnimatedImage is subclass of UIImage/NSImage, and SDAnimatedImageView is subclass of UIImageView/NSImageView, to make them compatible with the common frameworks APIs.

The SDAnimatedImageView supports the familiar image loading category methods, works like drop-in replacement for UIImageView/NSImageView.

Don't have UIView (like WatchKit or CALayer)? you can still use SDAnimatedPlayer the player engine for advanced playback and rendering.

See Animated Image for more detailed information.

  • Objective-C
SDAnimatedImageView *imageView = [SDAnimatedImageView new];
SDAnimatedImage *animatedImage = [SDAnimatedImage imageNamed:@"image.gif"];
imageView.image = animatedImage;
  • Swift
let imageView = SDAnimatedImageView()
let animatedImage = SDAnimatedImage(named: "image.gif")
imageView.image = animatedImage

FLAnimatedImage integration has its own dedicated repo

In order to clean up things and make our core project do less things, we decided that the FLAnimatedImage integration does not belong here. From 5.0, this will still be available, but under a dedicated repo SDWebImageFLPlugin.


There are four ways to use SDWebImage in your project:

  • using CocoaPods
  • using Carthage
  • using Swift Package Manager
  • manual install (build frameworks or embed Xcode Project)

Installation with CocoaPods

CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries in your projects. See the Get Started section for more details.


platform :ios, '8.0'
pod 'SDWebImage', '~> 5.0'
Swift and static framework

Swift project previously had to use use_frameworks! to make all Pods into dynamic framework to let CocoaPods work.

However, starting with CocoaPods 1.5.0+ (with Xcode 9+), which supports to build both Objective-C && Swift code into static framework. You can use modular headers to use SDWebImage as static framework, without the need of use_frameworks!:

platform :ios, '8.0'
# Uncomment the next line when you want all Pods as static framework
# use_modular_headers!
pod 'SDWebImage', :modular_headers => true

See more on CocoaPods 1.5.0 — Swift Static Libraries

If not, you still need to add use_frameworks! to use SDWebImage as dynamic framework:

platform :ios, '8.0'
pod 'SDWebImage'


There are 2 subspecs available now: Core and MapKit (this means you can install only some of the SDWebImage modules. By default, you get just Core, so if you need MapKit, you need to specify it).

Podfile example:

pod 'SDWebImage/MapKit'

Installation with Carthage

Carthage is a lightweight dependency manager for Swift and Objective-C. It leverages CocoaTouch modules and is less invasive than CocoaPods.

To install with carthage, follow the instruction on Carthage

Carthage users can point to this repository and use whichever generated framework they'd like: SDWebImage, SDWebImageMapKit or both.

Make the following entry in your Cartfile: github "SDWebImage/SDWebImage" Then run carthage update If this is your first time using Carthage in the project, you'll need to go through some additional steps as explained over at Carthage.

NOTE: At this time, Carthage does not provide a way to build only specific repository subcomponents (or equivalent of CocoaPods's subspecs). All components and their dependencies will be built with the above command. However, you don't need to copy frameworks you aren't using into your project. For instance, if you aren't using SDWebImageMapKit, feel free to delete that framework from the Carthage Build directory after carthage update completes.

Installation with Swift Package Manager (Xcode 11+)

Swift Package Manager (SwiftPM) is a tool for managing the distribution of Swift code as well as C-family dependency. From Xcode 11, SwiftPM got natively integrated with Xcode.

SDWebImage support SwiftPM from version 5.1.0. To use SwiftPM, you should use Xcode 11 to open your project. Click File -> Swift Packages -> Add Package Dependency, enter SDWebImage repo's URL. Or you can login Xcode with your GitHub account and just type SDWebImage to search.

After select the package, you can choose the dependency type (tagged version, branch or commit). Then Xcode will setup all the stuff for you.

If you're a framework author and use SDWebImage as a dependency, update your Package.swift file:

let package = Package(
    // 5.1.0 ..< 6.0.0
    dependencies: [
        .package(url: "https://github.com/SDWebImage/SDWebImage.git", from: "5.1.0")
    // ...

Manual Installation Guide

See more on Manual install Guide

Import headers in your source files

In the source files where you need to use the library, import the umbrella header file:

#import <SDWebImage/SDWebImage.h>

It's also recommend to use the module import syntax, available for CocoaPods(enable modular_headers)/Carthage/SwiftPM.

@import SDWebImage;

Build Project

At this point your workspace should build without error. If you are having problem, post to the Issue and the community can help you solve it.

Data Collection Practices

As required by the App privacy details on the App Store, here's SDWebImage's list of Data Collection Practices.




Thank you to all the people who have already contributed to SDWebImage.



All source code is licensed under the MIT License.


To learn about SDWebImage's architecture design for contribution, read The Core of SDWebImage v5.6 Architecture. Thanks @looseyi for the post and translation.

High Level Diagram

Overall Class Diagram

Top Level API Diagram

Main Sequence Diagram

More detailed diagrams


Stars: 23200


Used By

Total: 0


5.10.0 - iOS 9+/Xcode 11+ -


  • Bumped the min deployment target version to iOS 9, macOS 10.11. Bumped the min Xcode version to Xcode 11 #3130
  • This effect the downstream dependencies like SDWebImageWebPCoder, you may update them to the latest version at the same time.


Animated Image

  • Add animation playback mode for SDAnimatedImageView/Player, including reverse, bounce and reversed bounce #3115

Custom Loader

  • Added the options and context arg for Image Loader custom protocol, this can be used for advanced user to grab and check for context for current loading URL to process the logic #3129


  • Replace all current dispatch_semaphore usage into the os_unfair_lock, use OSSpinLock for lower firmware #3128

5.9.5 - 5.9 Patch -


  • Add animationImages support when using SDAnimatedImageView #3113

5.9.4 - 5.9 Patch -


  • Fix race condition when using transitions that are canceled and then switched to a new transition or load operation #3108 #3107
  • Fixed the store cache type was specified to SDImageCacheTypeDisk that no pictures were obtained when the disk had pictures #3110

5.9.3 - 5.9 Patch -


  • Fix coder priority inverse in SDAnimatedImage #3101
  • Fix that SDImageCache will automatically store the disk image into memory cache even if store cache type is disk #3104

5.9.2 - 5.9 Patch -


  • Fix the issue that SDAnimatedImageView will trigger an empty callback when animation stopped. This will cause some bad effect such as rendering a empty image or placeholder image (especially on iOS 14) #3092
  • Fix: duration is not used in SDWebImageTransition convenience initializers. #3094

5.9.1 - 5.9 Patch -


  • Fix the issue of SDAnimatedImage initWithContentsOfFile where the path name less than 3 characters #3081

5.9.0 - iOS 14 WebP -



  • Supports built-in WebP/AWebP codec from ImageIO for iOS 14/tvOS 14/macOS 11/watchOS 7 #3048
  • To use, add SDImageAWebPCoder to your coders manager. Note built-in WebP currently supports decoding only, for encoding, you still need SDImageWebPCoder
  • Add the support to pass small bytes to decodedAndScaledDownLargeImage, which always scale down (at least 1x1 pixel) but not return the original size #3067


  • Supports the user to customize the default disk cache directory, which can be used to share cache for App && App Extension #3066

View Category

  • Adjust the current behavior to use transition. Now it automatically do transition when manager callback asynchronously (if user see waiting, then do transition) #3074


  • Fix the bug when the thumbnail pixel size is larger than the pixel size, and the image has EXIF orientation, the final UIImage will use wrong image orientation #3070
  • Fix the image format detection for smaller SVG which less than 100 Bytes #3072

5.8.4 - 5.8 Patch -


  • Try to copy the local NSMutableDictionary before calling CGImageSourceCreateImageAtIndex, try to solve the rare crash inside ImageIO call stack #3052
  • Fix race condition when use transition but canceling an operation #3053

5.8.3 - Fix iOS 14 Beta -


  • Add the support for that UIImage+MultiFormat methods on SDAnimatedImage, which supports encoding the animation like GIF/APNG/WebP with lower compression quality #3047


  • Fix the issue of iOS 14 vector image rendering on SDAnimatedImageView #3046

5.8.2 - Fix iOS 14 Beta -


  • Fix the issue that SDAnimatedImageView can not render static image on iOS 14. #3043
  • Fix the maxPixelSize logic issue will cause a upscale in SDImageIOAnimatedCoder #3039

5.8.1 - 5.8 Patch -


  • Added the convenient transition with duration APIs #3027


  • Fix the issue that the NSURLRequest method should not be nil, which may cause Crash #3037
  • Fix the issue when maxPixelSize is larger than image size will cause a upscale in ImageIO #3015
  • Change to use kCGImageSourceCreateThumbnailFromImageAlways to solve the issue when HEIC/JPEG contains an embed thumbnail but its size is much smaller than provided maxPixelSize #3038
  • SDAnimatedImagePlayer seek returning nil image fix #3030
  • Fixing Typos throughout project #3026

5.8.0 - Transform original cache and more -



  • Add query original cache for transformed image without downloading #2992
  • This can be used to query the original image from cache then do transforming when transformed key cache miss, without any downloading happened.

Animated Image

  • Added autoplay control property to AnimatedImageView (autoPlayAnimatedImage) #3003


  • Mark the black list formal error code, support remove the failed URL from black list #2997
  • Polish the error description between image decode failed and image size is 0 #3005


  • Add the convenient request/response modifier, which provide HTTP header directly #2990

View Category

  • Added the convenient transition options for macOS user. Deprecate the old timingFunction, which can use System API to achieve #2985
  • Feature pass the set operation key into context option from upstream. Fix the potential retain cycle if user use custom manager #2986


  • Feature: Encoding options supports embed thumbnail (works for JPEG/HEIF/AVIF) #2988


  • Support the SwiftPM Objective-C user to use #improt <SDWebImage/SDWebImage.h> #2987

5.7.4 - Fix Prefetcher cancel -


  • Fix the issue that NSOperation conforms to SDWebImageOperation check failed. Fix cancelling prefetcher hung up #2999 #2998

5.7.3 - Fix Animated Encoding Options -


  • Fix the encoding options which does not passthrough the correct value to ImageIO #2989

5.7.2 - GIF OOM optimization -


  • SDAnimatedImageView animation rendering should not use CGContext force decoding, use kCGImageSourceShouldCacheImmediately instead which can avoid OOM for large number of GIFs #2977
  • Fix that when first play animated image and use maxBufferSize to 0, the calculation does not works (The CGImage is nil) #2982


  • Rename the private header UIColor+HexString and NSBezierPath+SDRoundedCorners with SD prefix, to avoid the conflict when using CocoaPods #2983

5.7.1 - 5.7 Patch -


  • Don't copy attributes from originalImage to transformedImage when caching transformedImage #2976. Thanks @bdaz
  • Fix the wrong value assignment for SDAnimatedImageView code on macOS, warning #2974

5.7.0 - Query Cache Type and Encoding Options -



  • Added the async version API to query disk image data only
  • Added the sync API to query disk image with context and options, which matches the async version


  • Feature supports encoding options like max file size, max pixel size, as well as background color when using JPEG for alpha image #2972
  • You can use .encodeMaxFileSize to limit the desired lossy file size, better than compression quality
  • You can use .encodeMaxPixelSize to limit the pixel size, like thumbnail encoding


  • Refactory the current thumbnail && transformer about cache key. Developer should have the API to calculate the cache key from thumbnail or transformer, not hard-coded. #2966

Context Option

  • Added new query cache type support, including the SDImageCache API and context option #2968
  • You use .queryCacheType to query image from memory/disk/both cache during image pipeline loading


  • Fix the issue for Carthage/SwiftPM framework version symbols, this should match the framework name SDWebImage, or will get a link error when used #2971 #2969
  • Simplify the xattr helper method's code with modern Objective-C syntax #2967. Thanks @huangboju


  • Change the behavior to return the abstract type for unknown image format, this can solve the accident issue for custom coder who provide a new format #2973

5.6.1 - 5.6 Patch -


  • Keep the progressive decoding process only exist one per image download. Cancel the unused progressive decoding when full pixel data is available. #2483


  • Fix the NotificationCenter does not remove the observer and little private header garden #2959

5.6.0 - URLSession Metrics && Vector Format -


URLSession Metrics

  • Added the URLSessionTaskMetrics support for downloader && operation, which can be used for network metrics #2937
  • Typically you use custom operation class to collect all metrics in your app. You can also collect metrics for single url request level. Check the #2937 example code to grab the download token and check metrics.

Vector Image

  • Feature - better support for vector format detection, now PDF rasterized bitmap is built-in #2936
  • Pass .thumbnailPixelSize to control the PDF bitmap size. If you want vector PDF rendering, you still need to use SDWebImagePDFCoder.
  • Vector image like SVG (via SDWebImageSVGCoder) and PDF (via SDWebImagePDFCoder), or system symbol images, can be detected by new API sd_isVector.
  • Vector image does not pass to transformer by default, because they support dynamic size changing. Pass .transformVectorImage option to allow transformation.


  • Add a better check to handle the cases when call storeImage without imageData #2953
  • Which means, if you store image to disk without data, we will use extra information via sd_imageFormat or custom image class, to choose the the image format (including GIF and PDF) for encoding. Previously we only encode it into PNG or JPEG.

Context Option

  • Feature add context option for cache, loader and coder, deprecated SDWebImageContextCustomManager #2955
  • This makes it easy to use custom loader, cache, and decoder, without need to create a dummy SDWebImageManager instance.


  • Fix the rare case when call SDWebImageDownloaderOperation.cancel, the completion block may callback twice #2954


  • Suppress the deprecation warning when min deployment target version set to iOS 13+ or macCatalyst
  • Complete all the SDWebImage error code with the localized description, make it easy for debugging #2948

5.5 Patch - AnimatedImage MaxBufferSize Fix -


  • Fix the issue that maxBufferSize property does not correctly works for SDAnimatedImageView #2934

5.5 Patch - Progressive Animation Fix -


  • Fix the SDAnimatedImageView's progressive animation bug, which reset the frame index to 0 each time new frames available #2931

5.4.3 - 5.4 Patch -


  • Fix the SDAnimatedImageView's progressive animation bug, which reset the frame index to 0 each time new frames available #2931

5.3.4 - 5.3 Patch -


  • Fix the SDAnimatedImageView's progressive animation bug, which reset the frame index to 0 each time new frames available #2931

5.5.0 - Thumbnail Decoding && Core Image -


Thumbnail Decoding

  • Supports to load the large web image with thumbnail, control the limit size and aspect ratio #2922 #2810
  • Better than resize transformer, which does not allocate full pixel RAM and faster on CPU. If you've already use transformer to generate thumbnail, you'd better have a try
  • Works for both animated images and progressive images, each frame using the thumbnail decoding
  • Applies for Vector Format like SVG/PDF as well, see more in Coder Plugin List

Core Image

  • Support all transformer method on CIImage based UIImage/NSImage #2918
  • For CIImage based UIImage/NSImage, using the CIFilter to take shortcut, which is faster and lazy (rasterize on demand)


  • Support to use the creation date and the change date to determine the disk cache expire date compare #2915


  • Using UIGraphicsImageRenderer on iOS 10+, save memory when image bitmap is RGB(-25%) or Grayscale(-75%) #2907
  • Provide the polyfill APIs for firmware iOS 10- and macOS. If you already use SDGraphicsBeginImageContext for drawing, you'd better replace that instead.


  • Fix Gaussian Blur's bug which take half of the blur radius compared to the standard, should match Core Image's behavior #2927

5.4.2 - 5.4 Patch -


  • SDAnimatedImage now only keep the animated coder when frame count >=1 , else we will behave like UIImage to save RAM usage #2924

5.4.1 - 5.4 Patch -


  • Fix the issue that "There may be no complete callback when download the picture of the local path" #2917

4.4.8 - 4.4 patch -


  • Fix the issue that "There may be no complete callback when download the picture of the local path" #2916
  • Fix the crash when using NSCache delegate with SDMemoryCache default implementation on dealloc #2899
  • Fix the thread safe issue with Downloader and DownloaderOperation during cancel #2903

5.4.0 Extended Cache Metadata -



  • Allows advanced user to read/write extended metadata associated with image data from disk cache #2898
  • This metadata will be processed at the same time when store or query the image. The metadata should conforms to NSCoding for archive and unarchive.


  • Add SDWebImageWaitStoreCache, which wait for all the async disk cache written finished and then callback, useful for advanced user who want to touch the cache right in completion block #2900


  • Using one global function to ensure we always sync all the UIImage category associated object status correctly inside our framework #2902
  • Fix the thread safe issue with Downloader and DownloaderOperation during cancel #2903

5.3 Patch - Memory Cache Delegate Fix -


  • Fix the crash when using NSCache delegate with SDMemoryCache default implementation on dealloc #2899

5.3 Patch - Animated Image Render Fix -


  • Fix animated image playback bugs that cause rendering frame is previous frame index #2895. Thanks @ZXIOU