Decouple component to load images
Pull request Compare This branch is 401 commits behind novoda:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Image loader is a simple library that give you the ability to decouple the logic to fetch, load and cache images.
It does that away from the ui thread, and by caching images with two levels in memory or in the sdcard if awailable.

Recent changes


In this release we added support to load a small image as a preview for a bigger image.


Improve cuncurrent loader, change sdcard image position to respect Android SDK guide lines and improved LruBitmapCache.

How to use the library

Using maven

If you are using maven you need to define the repo and then the dependency


Direct jar usage

If you don’t care about building tool you can just download the jar manually from this link

How to implement

The demo project is a good way to start. Import it in eclipse and check the task list to see where are all the TODO list.
If you are lazy this are the steps :


In the application add the folling code the instantiate the image loader:

public void onCreate() {
    LoaderSettings settings = new SettingsBuilder()
    imageManager = new ImageManager(this, settings);

public static final ImageManager getImageManager() {
    return imageManager;

This is setting up the image loader with size of the images that are taken from the display and the background image use while the image loader is fetching the real image.

The normal image loader works with softreferences. With a system with low memory as android, the system reclaim space to often. This limit the performance of the cache.

To avoid that we added a LruCache in the image loader library. This is very useful when you have lots of small images.

settings = new SettingsBuilder()
  .withCacheManager(new LruBitmapCache(this)).build(this);
thumbnailImageLoader = new ImageManager(this, settings);

By default the LruBitmapCache will take 25% of the free memory available for the cache. You can change that by using a different constructur:

settings = new SettingsBuilder()
  .withCacheManager(new LruBitmapCache(this, PERCENTAGE_OF_CACHE)).build(this);
thumbnailImageLoader = new ImageManager(this, settings);

Additional settings

Image loader use UrlConnection to fetch images. There are two important parameters that UrlConnection uses connectionTimeout and readTimeout.

SettingsBuilder builder = new SettingsBuilder();
Settings settings = builder.withConnectionTimeout(20000)

The connection timeout is the timeout in making the initial connection. The read timeout is the timeout on waiting to read data.

Preview image

Previe image works well when you have a list of items with small images chaced and then you go to the details to show a big image.
In fact image loader will take the small picture in the cache (only from the cache) and load in place of the big image before loading the real image.
To do that you have two ways : change image tag before calling the load method or change the ImageTagFactory.

//Image Tag after normal settings... add this: 

//If the small image used as preview has the same url of the big image
// you can use the image tag factory
imageTagFactory = new ImageTagFactory(this, R.drawable.loading);
imageTagFactory.usePreviewImage(THUMB_IMAGE_SIZE, THUMB_IMAGE_SIZE, true);
//keep the instance of the tag factory somewhere

//on the bind 
ImageView imageView = (ImageView) view;
String url = cursor.getString(columnIndex);

Cleaning up sdcard

If you want the image loader to clean up the sdcard, you can use the following line of code on the create of the application:


In the settings you can override the default expiration period that is set to 7 days.

In the activity

When you need to load the image in a view object you just need to get the imageLoader from the application and call load.
This is an example of a list view with the binder setting the url in the imageView as a tag.

ImageTagFactory imageTagFactory = new ImageTagFactory(this, R.drawable.bg_img_loading);

private ViewBinder getViewBinder() {
  return new ViewBinder() {
    public boolean setViewValue(View view, Cursor cursor, int columnIndex) {
      // TODO add this to your class
      ImageTag tag =
      ((ImageView) view).setTag(tag);
      return true;

The image loader will fetch the image from the cache if is still there or from the sdcard or will fetch the resource from the network in the worse scenario.

In the manifest

There are two things you need to add : Permissions and the service to clean up the files.

<uses-permission a:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission a:name="android.permission.INTERNET" />
<uses-permission a:name="android.permission.ACCESS_NETWORK_STATE" />

<service android:name="com.novoda.imageloader.core.service.CacheCleaner" android:exported="true">
    <action android:name="com.novoda.imageloader.core.action.CLEAN_CACHE" />

Helping out with the project

Report issues

If you have any problem with the library or new functionality you need to add, let us know and we will do something about it.
Send us a message or create an issue with github.

ImageLoader projects

  • core contains a java maven based project
  • demo mvn android based project to test imageLoader
  • acceptance mvn android based project with robotium test
  • monkey some example that take a snapshot using monkey runner (deprecated)

To build the projects :

  • run : mvn clean install -Peclipse

Parent project and core

Import the projects with maven, should be easy and painless.

For demo and acceptance

  • create a new android project in eclipse
  • add the necessary jars from the libs folder


  • maven 3.0.3+


Copyright © 2012 Novoda ltd
Licensed under Apache 2.0