How to install the Thumbor image CDN

Thumbor can be used for free to resize, compress, and transform images on-demand.

Katie Hempenius
Katie Hempenius

Image CDNs make it easy to dynamically optimize the aesthetics and performance of your images. Unlike most image CDNs, Thumbor is open-source and can be used for free to resize, compress, and transform images. It's suitable for production use; Wikipedia and Square both use Thumbor.

This guide explains how to install Thumbor on your own server. Once installed, you'll be able to use Thumbor as an API for transforming your images.


You'll be installing Thumbor on a VM running Ubuntu 16.04. Ubuntu 16.04 is a very common image and these instructions are intended to work on any cloud provider. Creating a VM might sound like more work than installing Thumbor on your local machine, but the minutes that you take to create a VM will probably save you hours or days of frustration trying to get Thumbor to properly install on your local machine. Although easy to use, Thumbor is notoriously difficult to install but these instructions simplify the process. If dependencies download quickly, the installation can be completed in 5 to 10 minutes.


This post assumes that you know how to create a Ubuntu 16.04 LTS VM on a cloud platform like Google Cloud, AWS, or Azure and how to use command line tools to set up the VM.

Install Thumbor Dependencies

Update and upgrade Ubuntu's already-installed packages:

sudo apt-get update -y && sudo apt-get upgrade -y

Install pip, the package manager for Python. Later you'll install Thumbor with pip.

sudo apt-get install -y python-pip

Install Thumbor's dependencies. Thumbor's documentation does not explicitly mention these dependencies, but Thumbor will not install successfully without them.

# ssl packages
sudo apt-get install -y libcurl4-openssl-dev libssl-dev
# computer vision packages
sudo apt-get install -y python-opencv libopencv-dev
# image format packages
sudo apt-get install -y libjpeg-dev libpng-dev libwebp-dev webp

Install Thumbor

Install Thumbor using pip.

sudo pip install thumbor

If you've successfully installed Thumbor, this should work:

thumbor --help

Run Thumbor

Run Thumbor. Debug logging is optional but can be helpful when you're getting started.

thumbor --log-level debug

Thumbor is now running.

Open Firewall Port

By default, Thumbor runs on port 8888. If your VM's IP address is, then you would access Thumbor from the web browser at$IMAGE.

However, this probably won't work for you (yet) because cloud providers usually require that you explicitly open firewall ports before they will accept incoming traffic.

Update the firewall to expose port 8888. Here's more information on how to do this for: Google Cloud, AWS, and Azure. Note that for Google Cloud you need to first assign a static IP address to your VM and then allow an external HTTP connection.

Try It Out

Thumbor is now accessible and ready for use. Try it out by visiting the following URL:


Note that this URL uses HTTP. Thumbor uses HTTP by default but can be configured to use HTTPS.

You should see an image that is 100 pixels wide by 100 pixels tall. Thumbor has taken the image hero.jpg and size specified in the URL string and served the result. You can replace the image in the URL string (i.e., with any other image (e.g., and Thumbor will resize that image too.

The Optimize images with Thumbor article has more information on using the Thumbor API. In particular, you may be interested in setting up a Thumbor configuration file.

Appendix: Configuring Systemd

This step explains how to make sure that the Thumbor process keeps running, even after the VM has been restarted. This step is important for production sites, but optional if you're just playing around with Thumbor.

Systemd is the "system and service manager" for Linux operating systems. systemd makes it easy to configure when services (processes) run.

You will be configuring systemd to automatically start Thumbor on VM boot. If the VM is restarted, the Thumbor process will automatically restart as well. This is much more reliable than relying on user intervention to start Thumbor.

Navigate to the /lib/systemd/system directory. This directory contains the service files for systemd.

cd /lib/systemd/system

As superuser, create a thumbor.service file.

sudo touch thumbor.service

Using your favorite text editor (vim and nano come pre-installed on Ubuntu or you can install another editor), add the following configuration to thumbor.service. This configuration will run /usr/local/bin/thumbor (i.e. the Thumbor binary) once networking is available and will restart Thumbor on failure.


Description=Service for Thumbor image CDN






systemctl is the utility used to manage systemd. Use the start command to start Thumbor.

sudo systemctl start thumbor.service

Next, "enable" Thumbor. This means that Thumbor will automatically start on boot.

sudo systemctl enable thumbor.service

Verify that you've successfully configured systemd by running the status command.

systemctl status thumbor.service

If you've successfully set up thumbor.service to use systemd, the status should show that it is enabled and active.

Systemctl displaying the status of Thumbor