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 UIImage (JPEG, PNG, HEIC, ...), including GIF/APNG/HEIC animation
  • WebP format, including animated WebP (use the SDWebImageWebPCoder project)
  • 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

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 with the functions (caching, loading and animation) powered by SDWebImage. You can have a try with SDWebImageSwiftUI

Coders for additional image formats


  • 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

Make our lives easier

You can use those directly, or create similar components of your own.


  • iOS 8.0 or later
  • tvOS 9.0 or later
  • watchOS 2.0 or later
  • macOS 10.10 or later (10.15 for Catalyst)
  • Xcode 10.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.


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. 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 have to use use_frameworks! to make all Pods into dynamic framework to let CocoaPods works.

However, start 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 (iOS 8+)

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>

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.




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



All source code is licensed under the MIT License.


High Level Diagram

Overall Class Diagram

Top Level API Diagram

Main Sequence Diagram

More detailed diagrams


Stars: 22532


Used By

Total: 0


5.6.1 - 5.6 Patch - 2020-03-13 12:50:40


  • 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 - 2020-03-05 10:49:59


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 - 2020-01-26 12:22:22


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

5.5 Patch - Progressive Animation Fix - 2020-01-18 12:26:35


  • 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 - 2020-01-18 11:10:11


  • 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 - 2020-01-18 11:02:42


  • 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 - 2020-01-16 11:24:26


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 - 2020-01-07 13:48:29


  • 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 - 2019-12-27 07:12:59


  • 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 - 2019-12-27 06:45:36


  • 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 - 2019-12-06 07:46:02



  • 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 - 2019-12-03 11:42:23


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

5.3 Patch - Animated Image Render Fix - 2019-11-22 08:24:21


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

5.3 Patch - Animated Image View Protect - 2019-11-09 07:18:46


  • Fix the case even when Animated Image View is not visible, user call startAnimating can still do animation #2888

5.3.0 - Animated Player & Data Decryptor - 2019-11-06 13:57:45


Animated Image

  • Refactoring the SDAnimatedImageView with player backend called SDAnimatedImagePlayer, make it easier for common usage. #2882
  • The player use protocol based implementation, which can be used for many scenarios, like WatchKit, CALayer, or even SwiftUI. See wiki
  • Supports the control of AnimatedImage View/Player 's play rate #2885
  • Supports the runloop mode control for macOS. Which can be useful when user want to pause animation when drag the mouse, or presenting modal window #2886

Data Decryptor

  • Decrypt the encrypted image data after download and just before decoding. #2866
  • Provide a built-in convenience for Base64-encoded image data. See wiki

Response Modifier

  • Modify the HTTP response after download, paired with request modifier #2866
  • Can be used for custom HTTP header check, mock data, etc. See wiki

5.2 Patch - Fix SDWebImageIndicator on macOS - 2019-10-27 06:01:19


  • Fix macOS SDWebImageIndicator center layout issue when indicator was initialized with 0 frame #2875

5.2 Patch - Fix SDAnimatedImageView on macOS - 2019-10-27 04:02:23


  • Fix the regression issue that SDAnimatedImageView on macOS will change the wrong duration speed when pause and resume again #2873
  • Fix SDAnimatedImage on macOS use extra animates property check, which is not intuitive and cause extra setup before usage #2874

5.2 Patch - Fix APNG on iOS 8 - 2019-10-09 09:44:14


  • Revert the change for APNG constants fix for iOS 8 devices which cause crash #2863

5.2 Patch - Fix warnings - 2019-10-02 08:43:10


  • Fix warnings when deployment target version set to iOS 13+ #2860 #2859

5.2 Patch - Fix token retain cycle - 2019-10-01 03:42:35


  • Make the SDWebImageDownloadToken to not retain the completion block so that user don't need weak-strong dance #2856 #2855


  • Try to fix the test case test15DownloaderLIFOExecutionOrder #2857

5.2.0 - Mac Catalyst && HEIC Animation - 2019-09-27 04:19:09


Mac Catalyst

  • Full compatible with Catalyst (UIKit for macOS)
  • Supports CococaPods and SwiftPM only. Carthage need their own toolchain upgrade in the future
  • Provide the build script to build xcframework contains Mac Catalyst variant, see Installation Guide.

Image Coder

  • Supports HEIC sequence (animated) image on iOS 13/macOS 10.15+ #2849
    • Note the HEIC animated coder does not enable by default. Add SDImageHEICCoder if you need the animation.
  • Refactor APNG and GIF coder implementation with abstract base class #2846
    • Now we use SDImageIOAnimatedCoder base class for all animated Image/IO coder implementation. Developer can get use of this as well.

Animated Image

  • Support to clear frame buffer or reset frame index when stopped for SDAnimatedImageView #2815


  • Fix the downloader LIFO order inverse issue when adding new urls during previous url query #2852 #2823
  • Fix the macOS SDAnimatedImageRep to match Netscape standard of GIF loop count, which should use 1 when there are no loop count information #2847 #2155

5.1 Patch - Fix SDAnimatedImageView - 2019-09-04 16:06:36


  • Fix that some option mask check with local BOOL variable, error result on 32 bit device. #2819 #2817
  • Fix the macOS that SDAnimatedImageView does not works for imageScaling and imageAlignment properties #2820
  • Fix the case when SDAnimatedImageView dealloc on the fetch queue, will cause it trigger the UIKit/AppKit method on non-main queue and captured by UI Main Thread Checker #2825

5.1.0 - SwiftPM and more - 2019-08-03 11:05:05


Swift Package Manager

  • Add support for Swift Package Manager #2756

Options Processor

  • Supports global control on options and context for individual image request #2736

Context Option

  • Supports store original image to cache for transformer via SDWebImageContextOriginalStoreCacheType #2590
  • Add a new option SDWebImageMatchAnimatedImageClass, to ensure we always match the custom image class instead of UIImage/NSImage class #2801


  • Expose the memoryCache and diskCache object on SDImageCache, Make it useful for user who have custom property beyond SDImageCacheConfig #2779


  • Fix SDAnimatedImageView's frame buffer bug when display link is pause #2782
  • Fix the bug that UIButton setBackgroundImage convenient method does not pass the options arg to next function call #2785
  • Add a autoreleasepool when prefetch many images #2792
  • Feature supports dynamic style indicator for iOS 13, fix indicator color on macOS 10.14+ #2753
  • Fix for CocoaPods modular headers warning by removing the custom modulemap #2749


  • Follow App Store submit rule, upgrade the minimum Xcode version to Xcode 10.0 #2780
  • Provide a script target to directly build all SDWebImage framework and generate all in one XCFramework from Xcode 11 #2764

Notable Behavior Changes

  • Ensure we always callback user's completion block even when cancelled with SDWebImageErrorCancelled error code #2692

This may effect some users. In previous 4.0~5.0 version, we will not callback completion block when we receive cancel call. (including all View Category/Cache/Manager/Downloader APIs)

But from 5.1, we always callback on this case with error code SDWebImageErrorCancelled. You can filter this error code if you don't care about cancel.

This change makes usages like Dispatch Group, observer, or any logic which relay on the completion's callback become acceptable, which is not reliable and will cause issue in previous versions.

  • Change that the sd_imageProgress property to not auto-create instance by framework #2763

Now, we don't create the NSProgress object from internal method call, this does not affect user's KVO usage.

  • Change the default value of accept request header #2772

Now, the default HTTP header filed Accept, use image/*,*/*;q=0.8, instead of image/*;q=0.8.

5.0 Patch - Xcode 11 Compatible - 2019-06-05 13:07:04


  • Fix the SDAnimatedImageRep which use the deprecated API and cause compile issue on Xcode 11 #2745

4.4.7 - 2019-06-05 12:45:47


  • Fix compatability for Xcode 11 #2744
  • Fix the SDAnimatedImageRep which use the deprecated API and cause compile issue on Xcode 11 #2745


  • Define SDWebImageDownloader convenience method #2633


  • Update libwebp constraint to lower 2.0 #2628

3.8.3 - 2019-06-05 05:01:26


  • Fix compatability for Xcode 11 #2744

5.0 Patch - Fix Static Library integration issue - 2019-06-03 12:45:33


  • Fix the Static Library target issue of headers, which cause the integrated application failed to Archive because of copied headers #2741

5.0 Patch - Fix UIButton issue - 2019-06-03 04:32:48


  • Fix get button background image operation key bug #2737
  • Fix that CGImageDestinationCreateWithData 0 count arg will log a warning #2739


  • Fix the example NSLog issue, and replace the unavailable test image dataset #2740

5.0 Patch - Fix animated image issue - 2019-05-16 11:38:17


  • Fix SDWebImageDecodeFirstFrameOnly flag is ignored when image loaded from cache #2725
  • Fix that SDAnimatedImageView initWithImage will skip the initialize logic and crash #2728
  • Replace if judge with MAX() function in scale less than 1 #2710


  • Replace the private prefix header files with the manually import for each implementation files #2723


  • Added many test case to ensure the code behavior and coverage #2711


  • Update the documentation coverage for jazzy. Use the correct format to provide class/protocol/type API Documentation #2722

5.0 Patch - Fix macOS render issue - 2019-04-25 14:17:20


  • Fix the bug of SDAnimatedImageView on macOS, which can only render SDAnimatedImage but not normal NSImage (including animated image) #2706
  • Fix that CGImageCreateDecoded:orientation: use the wrong aspect ratio when orientation is left/leftMirrored/right/rightMirrored #2708
  • Fix one bug of sd_colorAtPoint:, which set the alpha value default to 255 and should be 1. #2708


  • Fixes typo in SDImageCacheConfig maxDiskAge info #2699