Thumbnail configuration

Switching the thumbs driver

Kirby's thumb class supports two drivers for thumbnail generation: GD Lib and ImageMagick.

While GD Lib should be available by default on pretty much any server / shared hosting package and thus is the default driver for Kirby, ImageMagick can handle bigger images more efficiently and might be a better choice for larger images. If you have ImageMagick available on your server, you should definitely consider to switch.

The driver can be set in your config file:

// GD Lib (default)
c::set('thumbs.driver', 'gd');

// ImageMagick
c::set('thumbs.driver', 'im');

If the ImageMagick command is at a special location, you can define its path with the thumbs.bin option:

c::set('thumbs.bin', '/usr/local/bin/convert');

Changing the filename pattern for thumbnails

By default the pattern for thumbnail filenames follows this rule:


{safeName} stands for a sanitized version of the original filename of the converted image. {hash} is a unique identifier for all the applied options, like the width, height, quality, cropping, etc. and {extension} should probably be clear.

In case you want to change this pattern, you can do that in your config:

c::set('thumbs.filename', '{safeName}-{hash}.{extension}');

Available placeholders are…

placeholder info
{name} The name of the original file without extension
{safeName} The sanitized name of the original file without extension
{filename} The unsanitized name of the original file
{extension} the file extension
{hash} unique thumb options identifier
{width} The width of the generated thumbnail
{height} The height of the generated thumbnail

Changing the destination callback

If you want even more control over how and where thumbnails are stored, you can set your own thumb destination callback function. This callback will be called anytime a thumbnail is being generated in order to determin the filename and location where it should be stored. The callback can be set in your config file:

c::set('thumbs.destination', function($thumb) {

  // you must return a Kirby Object (obj) with the 
  // following attributes.   
  return new Obj(array(
    'root' => '/var/www/thumbs/customfilename.jpg',
    'url'  => ''


Modifying the thumb class defaults

You can change even more default settings of the thumb class by modifying the thumb::$defaults array.

For example:

thumb::$defaults['quality'] = 80;
thumb::$defaults['memory'] = '128MB';

Here's a list of all defaults of the thumb class:

Key Default value
destination false
filename {safeName}-{hash}.{extension}
url /thumbs
root /thumbs
driver gd
memory 128M
quality 90
blur false
blurpx 10
width null
height null
upscale false
crop false
grayscale false
overwrite false
autoOrient false