Custom Filters

Filters are an easy way to transform images using a pipeline. Creating a new filter is very simple, as we’ll see.

The first step is creating a filter class that inherits from thumbor.filters.BaseFilter and naming it Filter:

from thumbor.filters import BaseFilter

class Filter(BaseFilter):

The next step is actually implementing the filter. Let’s say we want to create the quality(99) filter, a filter that takes a number parameter and sets the image quality to that parameter.


Yep, this filter already exists and is built-in, but it is simple enough that we can talk on how to do it. Let’s get on with it.

from thumbor.filters import BaseFilter

class Filter(BaseFilter):
   async def quality(self, value):
      self.context.request.quality = value

Let’s analyse it:

  • The filter_method decorator takes as parameters any number of types (more on types below) you want to have as arguments to your filter;

  • The filter method should be named according to how you want it to be invoked by thumbor (a.k.a the URL part). In our example, our filter will be invoked with quality(99);

  • The filter method is just an async function that you can do whatever you need with the image.

And that’s it, we got our filter. In order to use it, we need to put it in our thumbor.conf:

from thumbor.filters import BUILTIN_FILTERS


Available Filter Argument Types

Each parameter type has a regular expression that matches arguments of the given type, as well as a python type.

For more details on each of the types, check BaseFilter class in thumbor’s codebase.

  • BaseFilter.PositiveNumber;

  • BaseFilter.PositiveNonZeroNumber;

  • BaseFilter.NegativeNumber;

  • BaseFilter.Number;

  • DecimalNumber;

  • Boolean;

  • String.