Latest 5.5.0
License MIT
Platforms ios 10.0, tvos 10.0, osx 10.12, watchos 3.0, requires ARC
Frameworks CFNetwork, Accelerate


codebeat badge

Kingfisher is a powerful, pure-Swift library for downloading and caching images from the web. It provides you a chance to use a pure-Swift way to work with remote images in your next app.


  • [x] Asynchronous image downloading and caching.
  • [x] Loading image from either URLSession-based networking or local provided data.
  • [x] Useful image processors and filters provided.
  • [x] Multiple-layer hybrid cache for both memory and disk.
  • [x] Fine control on cache behavior. Customizable expiration date and size limit.
  • [x] Cancelable downloading and auto-reusing previous downloaded content to improve performance.
  • [x] Independent components. Use the downloader, caching system and image processors separately as you need.
  • [x] Prefetching images and showing them from cache to boost your app.
  • [x] View extensions for UIImageView, NSImage, NSButton and UIButton to directly set an image from a URL.
  • [x] Built-in transition animation when setting images.
  • [x] Customizable placeholder and indicator while loading images.
  • [x] Extensible image processing and image format easily.

Kingfisher 101

The simplest use-case is setting an image to an image view with the UIImageView extension:

let url = URL(string: "")
imageView.kf.setImage(with: url)

Kingfisher will download the image from url, send it to both memory cache and disk cache, and display it in imageView. When you set with the same URL later, the image will be retrieved from cache and shown immediately.

A More Advanced Example

With the powerful options, you can do hard tasks with Kingfisher in a simple way. For example, the code below:

  1. Downloads a high-resolution image.
  2. Downsamples it to match the image view size.
  3. Makes it round cornered with a given radius.
  4. Shows a system indicator and a placeholder image while downloading.
  5. When prepared, it animates the small thumbnail image with a "fade in" effect.
  6. The original large image is also cached to disk for later use, to get rid of downloading it again in a detail view.
  7. A console log is printed when the task finishes, either for success or failure.
let url = URL(string: "")
let processor = DownsamplingImageProcessor(size: imageView.size)
             >> RoundCornerImageProcessor(cornerRadius: 20)
imageView.kf.indicatorType = .activity
    with: url,
    placeholder: UIImage(named: "placeholderImage"),
    options: [
    result in
    switch result {
    case .success(let value):
        print("Task done for: (value.source.url?.absoluteString ?? "")")
    case .failure(let error):
        print("Job failed: (error.localizedDescription)")

It is really a very common situation I can meet in my daily work. Think about how many lines you need to write without Kingfisher. You will fall in love with it if you give it a try!

Learn More

To learn the using of Kingfisher by more examples, take a look at the Cheat Sheet. There we summarized most common tasks in Kingfisher, you can get a better idea on what this framework can do. There are also some tips for performance in the same page, remember to check them too.


  • iOS 10.0+ / macOS 10.12+ / tvOS 10.0+ / watchOS 3.0+
  • Swift 4.0+

Kingfisher 5.0 Migration – Kingfisher 5.x is NOT fully compatible with version 4.x. However, the migration is not difficult. Depending on your use cases, it may take no effect or several minutes to modify your existing code for the new version. Please follow the migration guide when you prepare to upgrade Kingfisher in your project.

If you are using an even earlier version, see the guides below to know the steps for migrating.

  • Kingfisher 4.0 Migration – Kingfisher 3.x should be source compatible to Kingfisher 4. The reason for a major update is that we need to specify the Swift version explicitly for Xcode. All deprecated methods in Kingfisher 3 has been removed, so please ensure you have no warning left before you migrate from Kingfisher 3 to Kingfisher 4. If you have any trouble in migrating, please open an issue to discuss.
  • Kingfisher 3.0 Migration – If you are upgrading to Kingfisher 3.x from an earlier version, please read this for more information.

Next Steps

We prepared a wiki page. You can find tons of useful things there.

  • Installation Guide – Follow it to integrate Kingfisher into your project.
  • Cheat Sheet– Curious about what Kingfisher could do and how would it look like when used in your project? See this page for useful code snippets. If you are already familiar with Kingfisher, you could also learn new tricks to improve the way you use Kingfisher!
  • API Reference – Lastly, please remember to read the full whenever you may need a more detailed reference.


Future of Kingfisher

I want to keep Kingfisher lightweight. This framework will focus on providing a simple solution for downloading and caching images. This doesn’t mean the framework can’t be improved. Kingfisher is far from perfect, so necessary and useful updates will be made to make it better.

Developments and Tests

Any contributing and pull requests are warmly welcome. However, before you plan to implement some features or try to fix an uncertain issue, it is recommended to open a discussion first. It would be appreciated if your pull requests could build and with all tests green. :)

About the logo

The logo of Kingfisher is inspired by Tangram (七巧板), a dissection puzzle consisting of seven flat shapes from China. I believe she’s a kingfisher bird instead of a swift, but someone insists that she is a pigeon. I guess I should give her a name. Hi, guys, do you have any suggestions?


Follow and contact me on Twitter or Sina Weibo. If you find an issue, just open a ticket. Pull requests are warmly welcome as well.


This project exists thanks to all the people who contribute. [Contribute].


Thank you to all our backers! Your support is really important for the project and encourages us to continue. 🙏 [Become a backer]


Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]


Kingfisher is released under the MIT license. See LICENSE for details.

Latest podspec

    "name": "Kingfisher",
    "version": "5.5.0",
    "summary": "A lightweight and pure Swift implemented library for downloading and cacheing image from the web.",
    "description": "Kingfisher is a powerful and pure Swift implemented library for downloading and cacheing image from the web. It provides you a chance to use pure Swift alternation in your next app.nn* Everything in Kingfisher goes asynchronously, not only downloading, but also caching. That means you can never worry about blocking your UI thread.n* Multiple-layer cache. Downloaded image will be cached in both memory and disk. So there is no need to download it again and this could boost your app dramatically.n* Cache management. You can set the max duration or size the cache could take. And the cache will also be cleaned automatically to prevent taking too much resource.n* Modern framework. Kingfisher uses `NSURLSession` and the latest technology of GCD, which makes it a strong and swift framework. It also provides you easy APIs to use.n* Cancellable processing task. You can cancel the downloading or retriving image process if it is not needed anymore.n* Independent components. You can use the downloader or caching system separately. Or even create your own cache based on Kingfisher's code.n* Options to decompress the image in background before render it, which could improve the UI performance.n* A category over `UIImageView` for setting image from an url directly.",
    "homepage": "",
    "screenshots": "",
    "license": {
        "type": "MIT",
        "file": "LICENSE"
    "authors": {
        "onevcat": "[email protected]"
    "social_media_url": "",
    "swift_versions": [
    "platforms": {
        "ios": "10.0",
        "tvos": "10.0",
        "osx": "10.12",
        "watchos": "3.0"
    "source": {
        "git": "",
        "tag": "5.5.0"
    "source_files": [
    "public_header_files": [
    "osx": {
        "exclude_files": [
    "watchos": {
        "exclude_files": [
    "ios": {
        "exclude_files": [
    "tvos": {
        "exclude_files": [
    "requires_arc": true,
    "frameworks": [
    "swift_version": "5.0"

Pin It on Pinterest

Share This