Square Corner Blog
Published in

Square Corner Blog

Dynamic Images with Thumbor

Reduce memory, bandwidth, and disk usage.

Written by Jake Wharton.

Heads up, we’ve moved! If you’d like to continue keeping up with the latest technical content from Square please visit us at our new home https://developer.squareup.com/blog

Square uses a lot of user-generated images which are displayed on many mediums. An image for a single item can appear in the Dashboard, on a Market page, in the Register client (on an iPad, iPhone, or Android), in an email receipt, or in Wallet (on iPhone or Android). In order to do this in an efficient, consistent, and cross-platform way we leverage an application named Thumbor.

Thumbor is an open-source, on-demand image service which allows for server-side cropping, resizing, and compositing of images. This is particularly useful for applications where the density and resolution of the target screen can vary wildly. Rather than downloading a large image and scaling it to fit the display, the image is requested at the exact desired size and the server does the work on-demand to resize it before delivering.

Downloading images at exact sizes affords many benefits:

  • Reduced bandwidth — Smaller images download and display faster. As mobile usage continues to increase, wireless networks remain much slower than their desktop counterparts.
  • Reduced memory consumption — Since the image is the exact size that is required, apps and browsers do not have to scale it in memory. If the image is also cached in memory, this increases the quantity that you are able to store.
  • Reduced disk usage — Caching images to disk avoids unnecessary re-downloading. As with the memory cache, this allows for less space to be occupied for each image which allows for faster loads when there is a ‘miss’ in the memory cache.

Thumbor runs as a web application which uses specially constructed URLs to define how it behaves. The simple case of resizing the Google logo at 100px*100px we would use this URL:


Two security options that prevent others from abusing your service are opt-in: domain whitelisting and authentication. Whitelisting domains ensures Thumbor will only transform images which originate from your servers. Authentication uses a private key to add a checksum to the URL which is verified before performing the requested transformations. These two options restrict use to only allowed images and ensure that only the clients of your choosing can use the service. The secure version of the above URL becomes:


Thumbor has many options for transforming and compositing images. Combining multiple resize operations and arranging them into a single image further compounds all of the aforementioned positive effects. With all of these configuration options the URL can become very complex to construct. Square has developed two libraries to simplify this task.

Pollexor is a Thumbor URL builder for Java suitable for use both in server-side applications and Android clients.

Constructing the URL for the previous example using the Google logo becomes more declarative:

String u = image("http://www.google.com/images/srpr/logo3w.png")
.resize(100, 100)

Complex configurations can also be constructed in a clear, descriptive manner:

String u = image("http://example.com/background.png")
.resize(200, 100)

Our forthcoming ThumborURL library allows for easy URL creation for iOS-based clients.

NSURL *imageURL = [NSURL URLWithString:@"http://www.google.com/images/srpr/logo3w.png"];TUOptions *opts = [[TUOptions alloc] init];
opts.targetSize = CGSizeMake(100, 100);
NSURL *u = [NSURL TU_secureURLWithOptions:opts imageURL:imageURL baseURL:baseURL];

Using Thumbor has alleviated the burden of dealing with images of all different sizes in our clients while also allowing them to operate much more efficiently.




Buying and selling sound like simple things - and they should be. Somewhere along the way, they got complicated. At Square, we're working hard to make commerce easy for everyone.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Square Engineering

Square Engineering

The official account for @Square Engineering.

More from Medium

Security in Android 12 — For Developers

RecycleView Kotlin — Android Studio

How to Use Upserting in Room

Snapshot Testing in Android app using Shot library