Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Dynamic Image Transformation Module For nginx.
C Perl
Latest commit 20375cc @cubicdaiya v0.6.11 released.


ngx_small_light is a dynamic image transformation module for nginx. And ngx_small_light is written for using as the same way as mod_small_light as possible in nginx.(mod_small_light is an apache module)



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 following options when executing setup. (ImageMagick is always enabled)

./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

How To

See the configuration guide.

Configuration Example

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;


Supports following image-processings.

  • 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)

Supports following formats.

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

On the other hand, 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.

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, giving 1 to OMP_NUM_THREADS 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.


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

Running Test

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
Something went wrong with that request. Please try again.