Skip to content
Get packs

Guide · Open source

How to use thumbor: install, run and resize images on demand

Updated · written with AI from the project's own documentation and checked against our catalogue data

thumbor is an open-source image service, released under the MIT licence and written in Python, that crops, resizes and transforms photos on demand. This guide shows you how to install it, start the server, and request images at the sizes you need. By the end you will know how to build thumbor URLs and where to look when something goes wrong.

thumborthumbor/thumbor · ★ 10.5k · MIT

Quick start

  1. 1Choose an install method. Pick pip, the Debian or Ubuntu package, or the official Docker image based on your setup.
  2. 2Install thumbor. Run pip install thumbor, or use apt, or pull the Docker image.
  3. 3Start the server. Run thumbor, or run the Docker container with port 8888 published.
  4. 4Test with an example image. Open the localhost:8888/unsafe/ example URL in your browser to confirm the server returns an image.
  5. 5Request a resized image. Put the size, such as 300x200, and smart in the URL path before the image address.
  6. 6Run thumbor-doctor if needed. Run thumbor-doctor and include its output when you report a problem.

What thumbor does and how it works

thumbor is an HTTP server. Instead of storing every image size you need, you ask for the size and edits in the URL path, and thumbor returns the transformed picture.

It can apply cropping, resizing, filters and optimisation. It also uses AI-based detection, including face and feature detection, to choose a sensible crop so heads are less likely to be cut off.

  • Crop and resize on demand, without storing each variant
  • Smart detection for face and feature-based cropping
  • Storage options include local storage and AWS S3, among others
http://<thumbor-server>/300x200/smart/thumbor.readthedocs.io/en/latest/_images/logo-thumbor.png

Install thumbor with pip, apt or Docker

The README lists three options. The pip option installs thumbor from the Python package index. You can add extras: the opencv extra adds the OpenCV dependency, and the all extra installs every dependency. The README does not state a required Python version, so check the installation docs.

Thumbor is also packaged in the official Debian and Ubuntu repositories, so you can install it with apt. The Docker option uses the official image on GitHub Container Registry.

  • pip: install the base package, or use the opencv or all extras
  • apt: available in Debian and Ubuntu repositories
  • Docker: official image on ghcr.io
pip install thumbor pip install thumbor[opencv] pip install thumbor[all] sudo apt update sudo apt install thumbor docker run -p 8888:8888 ghcr.io/thumbor/thumbor:latest

Start the thumbor server

If you installed thumbor, run the thumbor command to start the server. From a development checkout, use make run instead.

When it is running, you can test it with an example image. The /unsafe/ path skips the security signature, which the README uses for this quick test. Keep it in mind for production use, where you should review how requests are secured in the documentation.

  • Installed copy: run thumbor
  • Development checkout: run make run
  • Docker: the container maps port 8888
thumbor http://localhost:8888/unsafe/https://raw.githubusercontent.com/thumbor/thumbor/master/example.jpg

Build image URLs for resizing and cropping

Image requests put the size and options in the path. The example in the README uses 300x200 for the size and smart for smart cropping, followed by the image location. Change the numbers to get a different size.

Other edits, such as filters, are documented in thumbor's docs. This guide only shows the forms given in the README.

  • 300x200 sets the output width and height
  • smart asks thumbor to choose the crop using its detection
  • The image address comes last in the path
http://<thumbor-server>/300x200/smart/thumbor.readthedocs.io/en/latest/_images/logo-thumbor.png

Troubleshoot with thumbor-doctor

If thumbor does not behave as expected, run thumbor-doctor. If you have a thumbor.conf file, pass it with -c so the tool can use your settings.

If you still need help, raise an issue on the thumbor GitHub repository and include the thumbor-doctor output. The --nocolor flag makes that output easier to paste.

  • Run thumbor-doctor for a general check
  • Pass -c thumbor.conf to use your config file
  • Use --nocolor when sharing output in an issue
thumbor-doctor thumbor-doctor -c thumbor.conf thumbor-doctor --nocolor -c thumbor.conf

What people use it for

  • Generating several thumbnail sizes of user uploads on demand
  • Serving correctly sized images to web pages without storing every variant
  • Resizing images stored in AWS S3 through a self-hosted server
  • Running image resizing on your own infrastructure for a development team

Frequently asked questions

Is thumbor free to use?

thumbor is open source under the MIT licence, as stated in the project information. You run it on your own infrastructure, so you pay for the servers you use.

How do I install thumbor?

Install it with pip using pip install thumbor, with apt on Debian or Ubuntu, or run the official Docker image. The README gives these commands directly.

What do I need to run thumbor?

You need Python and pip, or Docker if you use the container image. The README does not give a specific Python version, so check the installation docs.

Does thumbor work with S3?

Yes. The README lists AWS S3 among the supported storages, along with local storage and others.

Is thumbor a hosted service?

No. The README describes thumbor as a self-hosted server, so you need to run and secure it yourself.

What are the alternatives to thumbor?

The comparable projects listed for this guide are imgproxy, imaginary, sharp and Pillow. Choose based on whether you need a standalone server or a library in your code.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

thumbor suits web teams and developers who need many image sizes generated on demand and are willing to run a self-hosted server. If you only need to resize a few images once, a desktop image editor is simpler, and if you want a fully managed hosted service, pick a different tool.

Install options & downloads