developer-tools

📸 Thumbor

Thumbor is a self-hosted API-driven image editor -- make a web request and Thumbor will do the work to change the image.

AwesomeFOSS Team

Aug 4, 2024 • 4 min read

Thumbor (Code) is an API-driven image processing web service. This means that you can send a request to a Thumbor server URL and it will:

Download the image
Make modifications to the image (grayscale, blurring, dimensions, filters, etc)
Send the new (modified) image back to you.

It's a bit hard to understand maybe for non-developers – but to put it simply; ever with an image you found was just a slightly different size or had some filters applied (ex. grayscale)? With Thumbor you can do that with one HTTP call:

http://your-thumbor-server/300x200/smart/filters:grayscale()/thumbor.readthedocs.io/en/latest/_images/logo-thumbor.png

To break this down:

300x200 as part of the URL resizes the image
smart automatically tries to find the most important part of an image and focuses on it with some cropping
filter(grayscale) applies a grayscale filter
The last bit of the URL is the path to the actual image

Thumbor has been around a while and is trusted by some large companies:

Companies using Thumbor (source: Thumbor GitHub)

This is a huge time-saver for developers – instead of writing your own logic and code to take in an image, transform it, and return it (and then figuring out how to generalize that), Thumbor makes it easy to just deploy a service that instantly does the hard work for you.

Another great use case is that for people who build sites, getting an image that is optimized (possibly in a different format or dimensions) for your website and loads quick is just a URL away.

Thumbor is super popular and even has an "awesome Thumbor" page y0u can check out with a bunch of integrations and related codebases:

🌠 Features

Thumbor has a bunch of features, though they're mostly easy to guess by what it is:

Supports many image filters
API-driven self-hostable server
Automatic recognition of what is important in an image (smart setting)
Supports new image formats like .webp
Combinable image filters
Can convert images as well

🤖 As described by AI

Thumbor is an open-source image processing service designed to optimize and manipulate images on the fly. It provides a wide array of features, including resizing, cropping, flipping, rotating, and converting images to different formats. Thumbor excels in its ability to perform these operations dynamically through URL-based requests, making it highly flexible for web applications that need real-time image adjustments. Its support for smart cropping ensures that the most relevant parts of an image are preserved, enhancing the visual appeal and user experience.

One of Thumbor's standout features is its extensibility through filters and plug-ins, allowing developers to customize and extend its functionality to meet specific needs. It integrates seamlessly with various storage backends, such as local file systems, Amazon S3, and MongoDB, facilitating efficient image storage and retrieval. Thumbor's performance is optimized for speed and scalability, making it suitable for high-traffic environments where quick image processing is crucial. Overall, Thumbor provides a robust, versatile solution for dynamic image manipulation, empowering developers to deliver visually compelling content efficiently.

📺 Watch this

PyCon 2018 in Hong Kong had a great talk about Thumbor that serves as a great intro:

👟 Getting started

Thumbor is a Python project but also has an some unofficial docker images, so there are at least two ways to run it.

🐍 Running with Python

First, make sure you have the Python toolchain installed:

Then, you can follow what is a pretty normal flow thanks to the published thumbor pip package.

# thumbor with main dependencies only
pip install thumbor

Note that there are versions of Thumbor that come with more or less features – for the basic version, you can use the thumbor pip package as written above (see the pip instructions for more variants).

Once you have Thumbor installed, you can run it (assuming pip is properly installing to your $PATH):

thumbor

The server will run at localhost:8888 , and you can visit a URL like this:

http://localhost:8888/unsafe/https://raw.githubusercontent.com/thumbor/thumbor/master/example.jpg

🐳 Running with Docker

Unfortunately Thumbor doesn't have an official Docker image it looks like, but there are some trusted unofficial images, in particular, the minimalcompact/thumbor image.

Assuming you have a CPU with 8 hyper threads (~4 cores), you can run:

$ docker run \
  -p 8888:80 \
  -e THUMBOR_NUM_PROCESSES=8 \
  minimalcompact/thumbor

🧑‍💻 Want to contribute?

Thumbor is an MIT licensed project 10k ⭐s! It's ready for you to jump in and flex your Python prowess:

There is an incredibly small amount of issues open, but it's a great codebase to learn from, use and possibly contribute bug reports to.

📬 Want Awesome F/OSS in your inbox?

We'll send you new articles as soon as they go live.