Images preview with ngx_http_image_filter_module

Often on multimedia sites, there is the task of displaying pictures in various sizes (thumbnails). Moreover, in most cases, you have to support several dimensional versions of the pictures.

Today, We will describe a module with the name “ngx_http_image_filter_module”. This module allows you to solve the problem of resizing images directly through a Web server (without additional links). What does it all look like, and what needs to be done?


Download the latest version here:

To get started, you need to install libgd:

sudo apt-get install libgd2-xpm-dev

By default, the module we need is not going to be built, so it must be connected at the configuration stage of the nginx installation:

./configure --with-http_image_filter_module
sudo make install
Server configuration

Now we configure a virtual host in Nginx for image processing. Let the images be stored in the directory “/home/someuser/images” and we want to show two dimensional versions + the original. The rules are as follows:

When you query like “”, we will show a 150×150 version cropped around the edges (i.e. always square)

“ ” – shows the version inscribed in a 300×300 square

“ ” – shows the original image

Actually configuration:

# Resizing server
server {
        listen       444;
        server_name  localhost;

        location /z/ {
            proxy_pass     http://yourimageserver;  # Backend image server
            image_filter   crop  150 150;         # Resize photo 150x150 and crop
            error_page     415   = /empty;      # Handle error by /empty location

        # 'y' size 300x300
        location /y/ {
            proxy_pass     http://yourimageserver;
            image_filter   resize  300 300;     # Resize photo 300x300
            error_page     415   = /empty;

        # Original image
        location / {
            proxy_pass     http://yourimageserver; 

        # Error handler
        location = /empty {
            empty_gif;          # Respond with empty image

# Backend image server
server {
        listen       443;
        server_name  localhost;
        root /home/someuser/images;

        rewrite  ^/[zy]/(.*)$   /$1     last;

# Upstream
upstream yourimageserver {
    server localhost:444;

Now, if we have a picture called test.jpg in the folder “/home/youruser/images”, then we can test the server as follows:

localhost:444/example.jpg – shows the original image

localhost:444/z/example.jpg – will show version 150×150

localhost:444/y/example.jpg – show version 300×300

We raised the server on port 444, which renders different versions of the pictures. Each version has a separate location directive. What interests us is the image_filter directive. We used it in two versions:

image_filter resize A B – reduces the image proportionally to fit into the specified dimensions AhV

image_filter crop A B – reduces the image and cuts off the large e side at the edges so that the final size exactly matches AxB

The server listening on port 443 outputs images from the folder “/home/someuser/images”, and rewrites the path if there is a size prefix (/ y / or / z /) using the rewrite directive.

If the event of a resizing error, the module gives a 415 error that can be processed. In our example, in case of such an error, we show an empty gif.

You can read more Linux guides by link ttps://

Viva La Linux!

Leave A Comment