BoxLang 🚀 A New JVM Dynamic Language Learn More...

Preside Extension: libvips image processing

v1.0.11+0000005 Preside Extensions

VIPS Image processor

This extension swaps out the ImageMagick/native lucee implementation of image resizing in favour of using libvips.

It requires Preside 10.11 or greater (recommended 10.11.25) and as of 10.14.0, is included in the Preside core (so not required).


box install preside-ext-vips

Pre-requisites and configuration

It is expected that libvips be installed on your system, along with libexif. For example, on Ubuntu:

apt install libvips-tools --no-install-recommends

Or on MacOS, install with Homebrew:

brew install vips

Once installed, you can configure vips in your Config.cfc. Note: You only need to do this if you need non-default values. Defaults are shown below:

function configure() {
	// ...

	settings.vips.binDir  = "/usr/bin/"; // where vips tools binary files are found
	settings.vips.timeout = 60;          // longest time to wait for a VIPs operation to complete

	// ...

(If installing on MacOS via Homebrew, your binDir is likely to be /usr/local/bin/.)

Environment variables

You can also configure vips using environment variables, and this is in fact the method we would recommend, both for dev and live environments.

In a .env file for your site, tyou could set:


And by setting PRESIDE_VIPS_BINDIR or PRESIDE_VIPS_TIMEOUT as environment variables on a local dev environment, those values will be picked up by every Preside site running under CommandBox - no further configuration required!

Additional features

There are a couple of additional features that are available to your derivatives when using the VIPS extension.


Normally, an image will be output in the same format as the original (unless the original image is an SVG file, in which case a PNG will be generated).

By adding the outputFormat argument to a derivative, you can specify which format the resulting image should be in. This is especially useful for a modern format such as WebP. You could specify outputFormat="webp" and the resulting images would be generated in the WebP format.

(Note that you would want to implement these images as alternate sources using the <picture> element, as not all browsers support WebP).

Related to this, .webp is added to Preside's known image formats by the VIPS extension.


Note: this is only available if your version of libvips is 8.5.0 or above. Some Linux distributions may not meet this requirement.

You already have the ability to specify the focal point of an image manually. However, if you set autoFocalPoint=true on your derivative, then VIPS will make a smart guess at where the centre of attention of the image is. This would be especially useful for portraits, where you might want to automatically crop to a person's face.

Of course, if you manually set the focal point, then that will be used in preference - there may be occasions where the algorithm doesn't pick out the focal point you desire.


  • We have not yet implemented the conversion of pages of PDFs into jpgs. We leave the PDF Preview transformation to ImageMagick/native Lucee implementation.


This project is licensed under the GPLv2 License - see the LICENSE.txt file for details.


The project is maintained by The Pixl8 Group. The lead developer is Dominic Watson. Contribution in the form of issues, ideas and pull requests is most welcome and encouraged.

Code of conduct

We are a small, friendly and professional community. For the eradication of doubt, we publish a simple code of conduct and expect all contributors, users and passers-by to observe it.



  • #23 Fix issues with Lucee deleting the tmp directory that we create for VIPS operations. Always ensure it exists when retreiving it for use.


  • #22 Ensure scaleToFit operations cannot make resultant image smaller than the provided dimension
  • Convert to Github actions publishing flow


  • #21 Return width and height of generated asset derivative


  • #20 Issue with dimension rounding and certain combinations of source/target sizes


  • #19 Fix regression where SVG resizing was not working on all systems (revert previous change).


  • #17 AutoFocalPoint fails on older versions of libvips


  • #13 Configure VIPS using environment variables
  • #14 Update Ubuntu install instructions


  • #7 Use VIPS for SVG-to-PNG conversion
  • #8 Allow derivatives to specify an output format
  • #9 Add .webp as a recognized image format
  • #10 Add automatic focal point detection
  • #11 Fix crop hints being ignored by the VIPS processor


  • #3 Fix further rounding issues (workaround Lucee 5 bug)
  • #5 Strip EXIF metadata when producing thumbnails
  • #6 Implement image quality settings


  • #1 Fix issue with non-integer dimension handling
  • Added OSX installation instructions for libvips binaries


  • Fix download location for box install


Initial release with support for resizing images (no PDF image sizing). Image quality arguments are also ignored in this release.

$ box install preside-ext-vips

No collaborators yet.
  • {{ getFullDate("2020-01-23T05:09:13Z") }}
  • {{ getFullDate("2021-01-19T12:43:29Z") }}
  • 2,863
  • 98,843