Skip to content
Dynamic Image Transformation Module For nginx.
C Perl
Latest commit ab0ce47 May 20, 2016 @cubicdaiya changelog: typo fixed.


A dynamic image transformation module for nginx.

Table of contents


Supports the various image-processings below.

  • Resize
  • Rotate
  • Sharpen
  • Unsharpen
  • Blur
  • Border
  • Canvas
  • Crop
  • Composition
  • JPEG Hinting(except GD)
  • Format convert(e.g. PNG -> JPEG)
  • Color-space convert(e.g. CMYK -> sRGB)

ngx_small_light is developed for using as the same way as mod_small_light as possible in nginx.

Supported Formats

Supports the formats below.

  • JPEG
  • GIF(except Imlib2)
  • PNG
  • WebP(except Imlib2)



cd ${ngx_small_light_src_dir}
cd {$nginx_src_dir}
./configure --add-module=${ngx_small_light_src_dir}
make install

If you want to enable the libraries except ImageMagick in ngx_small_light, add the options below when executing setup. (ImageMagick is always enabled)

./setup                         # enable ImageMagick
./setup --with-imlib2           # enable ImageMagick and Imlib2
./setup --with-gd               # enable ImageMagick and GD
./setup --with-imlib2 --with-gd # enable ImageMagick and Imlib2 and GD

Dynamic module

You can also compile ngx_small_light as the dynamic module with --add-dynamic-module from nginx-1.9.11 and ngx_small_light-0.6.15.

cd ${ngx_small_light_src_dir}
cd {$nginx_src_dir}
./configure \
--modules-path=/usr/local/nginx/modules \
make install

Add the configuration below for loading module dynamically.

load_module /usr/local/nginx/modules/;

Getting started

Add the configuration below to some server context in nginx.conf and start nginx.

small_light on;
location ~ small_light[^/]*/(.+)$ {
    set $file $1;
    rewrite ^ /$file;

If you can get the original image of image.jpg from the URL below,


You will be able to get the converted image of image.jpg from the URL below.


The part of small_light(...) is called small_light function.

Configuration example

There is some configuration example below.

server {
    listen 8000;
    server_name localhost;

    small_light on;
    small_light_pattern_define msize dw=500,dh=500,da=l,q=95,e=imagemagick,jpeghint=y;
    small_light_pattern_define ssize dw=120,dh=120,da=l,q=95,e=imlib2,jpeghint=y;

    # http://localhost:8000/small_light(p=msize)/img/filename.jpg -> generate msize image
    # http://localhost:8000/small_light(p=ssize)/img/filename.jpg -> generate ssize image
    # http://localhost:8000/small_light(of=gif,q=100)/img/filename.jpg -> generate gif image which quality is 100
    location ~ small_light[^/]*/(.+)$ {
        set $file $1;
        rewrite ^ /$file;



Syntax small_light on | off
Default off
Context server, location

This directive sets whether image-processing with ngx_small_light is enabled in a server context.


Syntax small_light_getparam_mode on | off
Default off
Context server, location

This directive sets whether converting-image is enabled by GET parameters instead of small_light function (e.g. /small_light(dw=200,dh=200)). At the expense of it, a small_light function is disabled. But you need to set both small_light and small_light_getparam_mode on to enable the feature of this directive.


Syntax small_light_material_dir path
Context server

This directive assigns the directory for embedded icon images.


Syntax small_light_pattern_define pattern_name parameters
Context server

This directive names comma-delimited parameters.


Syntax small_light_radius_max number
Default 10
Context server,location

This directive sets maximum radius value of geometry for sharpen and unsharp and blur.


Syntax small_light_sigma_max number
Default 10
Context server,location

This directive sets maximum sigma value of geometry for sharpen and unsharp and blur.


Syntax small_light_imlib2_temp_dir path [level1 [level2 [level 3 ]]]
Default /tmp 1 2
Context server

This directive assigns the directory for temporary file for Imlib2 processing.


Syntax small_ligh_buffer size
Default 1m
Context server

This directive assigns the maximum size of the buffer used for reading images when Content-Length is not set in response headers.

Parameters for small_light function

Parameter Type Default Description ImageMagick Imlib2 GD
p string named pattern of comma-delimited parameters
e string imagemagick engine name(imagemagick, imlib2, gd)
q number quality
of string output format(jpg, gif, png, webp)
jpeghint char n enable jpeg hinting
dw coord sw destination width
dh coord sh destination height
dx coord sx destination x coordinate
dy coord sy destination y coordinate
da char l destination aspect ratio contol
ds char n destination scaling control(s, n)
cw number canvas width
ch number canvas height
cc color 000000 canvas color
bw number border width
bh number border height
bc color 000000 border color
sw coord source witdh
sh coord source height
sx coord source x coordinate
sy coord source y coordinate
pt char n pass through control
sharpen string radius,sigma
unsharp string radius,sigma,amount,threshold
blur string radius,sigma
embedicon string embedded icon file in small_light_material_dir
ix number 0 embedded icon x coordinate
iy number 0 embedded icon y coordinate
angle number 0 angle of rotation(90, 180, 270)
progressive char n make JPEG progressive
cmyk2rgb char n convert colorspace from CMYK to sRGB
rmprof char n remove profile
autoorient char n enable adjust image orientation automatically

There are any limitations below.

  • of=gif and of=webp are not supported when e=imlib2.
  • autoorient is available ImageMagick-6.9.0 or later.
  • The value of radius,sigma for sharpen and unsharp and blur is limited by small_light_radius_max and small_light_sigma_max.

There are the types of each parameter below.

Type Description
coord coordicante or pixel. percent when appending 'p'
char character
number integer number
color rrggbb or rrggbbaa
string string

Named Pattern

ngx_small_light supports to name comma-delimited parameters with the small_light_define_patern.

small_light_pattern_define small dw=120,dh=120,q=80,e=imagemagick,jpeghint=y;

If the line above is added to some server context in nginx.conf, the two URLs below return same response.

  • http://$host:$port/small_light(p=small)/img/image.jpg
  • http://$host:$port/small_light(dw=120,dh=120,q=80,e=imagemagick,jpeghint=y)/img/image.jpg

Using GET parameters

ngx_small_light supports to convert image not only by small_light function but by GET paramenters from v0.5.0. You need to set both small_light and small_light_getparam_mode on to enable this feature. At the expense of enabling this feature, small_light function (e.g. /small_light(dw=300,dh=300)/img.jpg is disabled.

small_light on;
small_light_getparam_mode on;

In the configuration above, the url below does not return converted image.


Instead the url below returns converted image expected by right.


Or you can avoid this problem by building ImageMagick with --disable-openmp.

Optimizing Tips

When the output format is JPEG and image-converting engine is ImageMagick or Imlib2, you may give 'y' to the parameter jpeghint. The speed of processing images is improved dramatically.

And when image-converting engine is ImageMagick and the version of ngx_small_light is lower than v0.6.14, giving 1 to OMP_NUM_THREADS or MAGICK_THREAD_LIMIT in nginx.conf is recommended strongly. Because OpenMP is enabled in ImageMagick by default and ImageMagick enabled OpenMP is very slow on multi-process environment.


From v0.6.14, ngx_small_light sets the thread-number with OpenMP 1 always.


ngx_small_light has the limitations below.

Not supported features with Imlib2

The transformation with Imlib2 does not support to write GIF-image. Because Imlib2 has the function for loading GIF-image but does not have the function for saving. Additionally, the transformation by Imlib2 does not support to write and read WebP-image. So of=gif and e=imlib2 are not enabled to specify at once. If these are specified, ngx_small_light returns 415(Unsupported Media Type).

Not supported features with GD

The transformation with GD supports to write WebP-image. But it is the experimental feature.

Not supported animated GIF

ngx_small_light does not suport Animated GIF. Because it takes long time to transform(e.g. resize, crop) Animated GIF with animation. So it is not realistic for ngx_small_light to support an animated GIF.

Running Tests

perl Build.PL
cpanm --installdeps .
NGINX_BIN=${nginx_prefix_dir}/sbin/nginx ./Build test
# or
NGINX_BIN=${nginx_prefix_dir}/sbin/nginx prove t/**/*.t


Please read the COPYING.

Something went wrong with that request. Please try again.