Open-source project
thumbor/thumbor avatar
thumbor/thumbor

thumbor: the URL-driven thumbnail server, and the parts the short install leaves out

thumbor is an open-source photo thumbnail service by globo.com

10,531 stars862 forksPythonMIT

At a glance

What is it?
thumbor is globo.com's Python imaging service that generates crops, resizes and filtered images purely from the request path. The interesting decisions live in what a bare install omits: no OpenCV, no version pin on the container tag, and C filters compiled at install time with warnings promoted to errors.
Who is it for?
Adopt thumbor when you want URL-addressed image transforms you can change without redeploying an asset pipeline, and you are willing to install the extras. Do not adopt it on the strength of the plain pip install, because the detection features that motivate it are not in that install.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • thumbor/thumbor10,531 ★ · +12
Star history
Repository2026-09-222026-11-15
thumbor/thumbor10.5k10.5k

12 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The URL is the whole API, and the sample URL carries /unsafe/

thumbor is an HTTP server, and every image it produces is defined by a path. Dimensions come first, then a transformation segment, then the source URL:

`http://<thumbor-server>/300x200/smart/thumbor.readthedocs.io/en/latest/_images/logo-thumbor.png`

That request returns the thumbor logo at 300x200. The `smart` segment is the one worth understanding: it is the switch for AI-assisted detection, which the project positions as its answer to automatic cropping that decapitates people.

What the README never explains in place is the `/unsafe/` prefix, and that is exactly the segment in its own local example: http://localhost:8888/unsafe/https://raw.githubusercontent.com/thumbor/thumbor/master/example.jpg. So the first URL a new operator copies into a browser, and then into a deployment, contains a prefix whose meaning lives on a separate documentation site rather than in the install instructions. Read what the prefix your URL uses actually permits before you expose the server, because the sample you are handed leads with the one variant that has a name worth looking up.

The shortest pip install has no OpenCV, so it has no smart cropping

Three install forms sit under the same package name, and what they add is not symmetrical. The plain form pulls only the declared dependencies: colorama, derpconf, JpegIPTC, libthumbor, piexif, Pillow, pytz, statsd, thumbor-plugins-gifv and tornado. OpenCV is absent from that list. It arrives with the `opencv` extra, which also brings numpy, and `all` sits above that.

The consequence is that the feature the project leads with is not in the shortest install. Face and feature detection, glasses and interesting points, all of it lives behind `pip install thumbor[opencv]`. Someone who runs `pip install thumbor`, starts the server, and requests a `smart` URL ends up exercising the non-detection path while believing they are exercising the headline feature.

Also worth noting is what the default bundle does include. tornado is the web layer, statsd is the metrics sink, and thumbor-plugins-gifv is present as a dependency.

Filters compile from C at install time, and warnings are errors

setup.py is not a shim. It globs `thumbor/ext/filters/_*.c` together with every C file under `thumbor/ext/filters/lib/`, builds each one as an Extension linked against the math library, and passes `-Wall -Wextra -Werror -Wno-unused-parameter`. The modules are declared with `py_limited_api=True` and `Py_LIMITED_API` set to `0x03080000`, so filters are compiled against the stable ABI rather than against one Python version.

Two things follow for an operator. A source install needs a working C toolchain, which the Makefile makes explicit for checkouts with a dedicated compile step that runs `python setup.py build_ext -i` in place. And `-Werror` promotes any compiler warning to a build failure, so a toolchain newer than the one the maintainers used can stop your install before it serves a single request. When that happens the error text names a warning rather than a fault in thumbor, which sends you hunting through the wrong file.

Three install routes, and only one of them is pinned to anything

Three routes exist and they age differently. pip gives you the newest release and full access to the extras. The distribution package comes from Debian and Ubuntu, installed the ordinary way:

bash
sudo apt update
sudo apt install thumbor

The official image lives on GitHub Container Registry:

bash
docker run -p 8888:8888 ghcr.io/thumbor/thumbor:latest

The tag is the problem in that last line. `latest` is not a version, so pulling the image again on a later date can hand you different code, and the README does not map image tags to releases. The distro route has the same problem in slower motion: you receive whatever your Debian or Ubuntu release shipped, which may be several releases behind 7.8.0. Nothing in the README explains how to pin a version across routes or how to move an existing install from one route to another, so this choice is close to permanent unless you plan the migration yourself.

thumbor-doctor reports a host, and it wants your config path most of all

An installed copy starts as a single command:

bash
thumbor

When something is wrong, the project's answer is a second command:

bash
thumbor-doctor

It takes a config path, which the README says helps thumbor-doctor:

bash
thumbor-doctor -c thumbor.conf

For an issue report it adds --nocolor so the pasted block stays readable:

bash
thumbor-doctor --nocolor -c thumbor.conf

Two limits are worth naming. The README documents no error text for individual failures, so thumbor-doctor is a report generator rather than a checklist you can work through before starting a server. And from a development checkout the same command runs through `uv run --locked thumbor-doctor`, which means the diagnostic depends on a locked dependency set. A checkout that has drifted from its lockfile cannot run the tool meant to explain what is wrong with it.

Contributing means Redis, uv 0.11.19, and a lockfile you keep in step

The development path is four make targets:

bash
make setup
make pre-commit  # only needed once per clone
make compile_ext
make test

`make setup` uses an existing uv install or bootstraps the pinned version, 0.11.19, into `.uv-venv`, with the environment itself landing in `.venv`. Everything afterwards runs through `uv run --locked`, and the README states that the lockfile is managed with `uv lock` and should be committed when dependencies change. So editing dependencies in pyproject.toml without regenerating uv.lock produces no warning; it makes every `--locked` invocation in the Makefile fail, which is a confusing first hour for anyone new to the codebase.

The heavier constraint is `make test`. That target depends on a redis target and finishes with kill_redis, and the repository root carries both redis.conf and redis-sentinel.conf. Unit tests, coverage, the integration run and the flake step all live inside that one target, so a full test run needs a local Redis.

Six days between patches, then twelve months before 7.8.0

The release record is short and uneven. 7.7.6 landed on 2025-05-09 and 7.7.7 on 2025-05-15, six days apart, which is the shape of an actively patched line. Then 7.8.0 arrived on 2026-05-30. The repository's last push was on 2026-11-02, so work has continued on master for over five months since that tag without a release carrying it.

For a service that fetches and rewrites user images, that gap sets your upgrade policy. Anything merged after 2026-05-30 exists only in master, so an operator who wants one specific fix has no release to pin and must build from a commit instead. An operator who wants the newest fixes pins nothing and accepts drift. Both are defensible, and the README recommends neither, so the decision is yours rather than a default you inherit.

The repository is not archived, and the packaging metadata still classifies it as Development Status :: 4 - Beta with requires-python of at least 3.11 and classifiers covering Python 3.11 through 3.15.

No comparison against another service, just a curated list of extensions

Readers arrive looking for a side-by-side and the project does not offer one. No throughput figure, no latency number, and no comparison appears anywhere in the README. That reads as omission by design, because the alternative the project puts in front of you is composition rather than substitution.

That alternative is awesome-thumbor, a curated list holding filters, storages, engines, loaders, docker images, and extensions written for different languages and frameworks, each entry carrying a quality indication. The default package already leans on this model, since thumbor-plugins-gifv ships as a dependency instead of living in the core.

So the way to judge fit is to read which engines and storages exist, not to look for a score. If your workload is a set of images behind a CDN, swapping the storage backend or the imaging engine is a configuration change inside thumbor, and the real question becomes which one to pick rather than whether thumbor belongs in the stack at all. Licensing is plain: MIT, with LICENSE at the repository root.

Editorial conclusion

Adopt thumbor when you want URL-addressed image transforms you can change without redeploying an asset pipeline, and you are willing to install the extras. Do not adopt it on the strength of the plain pip install, because the detection features that motivate it are not in that install. Before committing, run thumbor-doctor against your real thumbor.conf, request one smart URL with the opencv extra installed to confirm detection is active, and pin the container to a release tag rather than latest, because the Docker command the README gives uses the moving latest tag.

Frequently asked questions

What are the alternatives to thumbor?

thumbor does not name a competing service in its README. What it offers instead is awesome-thumbor, a curated list of filters, storages, engines, loaders, docker images and extensions for different languages and frameworks, each marked with a quality indication.

Does pip install thumbor include OpenCV for smart cropping?

No. The declared dependencies are colorama, derpconf, JpegIPTC, libthumbor, piexif, Pillow, pytz, statsd, thumbor-plugins-gifv and tornado. OpenCV comes from the opencv extra, which also pulls numpy.

How do you run thumbor from the official Docker image?

Pull the official image from GitHub Container Registry and map port 8888: docker run -p 8888:8888 ghcr.io/thumbor/thumbor:latest. The documented tag is latest rather than a release number, so the image is not pinned.

When should you run thumbor-doctor?

The README calls it out as the first thing to try when you hit trouble, including when you have a config file to point it at. For an issue report it asks for thumbor-doctor --nocolor -c thumbor.conf so the output pastes cleanly.

What does running the thumbor test suite require?

make setup uses an existing uv or bootstraps the pinned 0.11.19 into .uv-venv, then make compile_ext and make test. The test target depends on redis and ends with kill_redis, and the repository ships redis.conf and redis-sentinel.conf.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. thumbor/thumbor on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/thumbor-thumbor.svg)](https://hysenlabs.com/projects/thumbor-thumbor)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/thumbor-thumbor.svg)](https://hysenlabs.com/projects/thumbor-thumbor)

Was this useful?