Going to Production

If you are starting from a filename and want a thumbnail, prefer ops/thumbnail over loading the full image and then calling ops/resize. Unlike a separate load followed by resize, ops/thumbnail combines loading and shrinking into one step. That lets libvips use format-specific tricks such as shrink-on-load, which can significantly reduce memory use and latency.

This is not only about speed. Thumbnailing at load time can also improve quality, because libvips can premultiply automatically where needed and can render vector inputs at the target size instead of rasterizing them large and shrinking afterwards.

If you already have an image handle in hand, there is still a lower-level ops/thumbnail-image wrapper. Treat it as an escape hatch. It wraps libvips thumbnail_image, so it does not get the load-time rendering and shrink-on-load advantages that ops/thumbnail gets from starting at the source.

When you know you will read the source once in loader order, pass {:access :sequential} to your loader. This often reduces memory use and can improve throughput.

For background on why this matters, see the upstream libvips "How it opens files" chapter.

The same applies to v/from-stream, v/from-buffer, and format-specific loader operations such as ops/jpegload and ops/pngload.

libvips is demand-driven and uses partial images as intermediates. In ol.vips, that means you can usually build one longer pipeline of operations without materializing every step in memory or on disk. The work is deferred until a sink asks for pixels, such as v/write-to-file, v/write-to-buffer, or v/write-to-stream.

This is one of the main reasons to lean into the libvips model instead of breaking processing into many disconnected phases. Long pipelines usually stay memory-efficient because intermediate results are represented as graph nodes rather than fully realized images.

libvips is also horizontally threaded: threads tend to run along the pipeline you are evaluating, rather than up and down the image. In practice, that means longer pipelines often parallelize better than shorter ones.

If you can, aim for one coherent processing pipeline per output rather than a series of intermediate writes, reloads, and separate mini-pipelines.

This generally works better than repeatedly writing intermediates to disk or breaking the flow into many disconnected steps.

If one derived image is reused several times in the same request, bind it once and pass that handle to downstream operations instead of recalculating it.

If you need to materialize a reused intermediate so libvips does not recalculate it, use v/copy-memory. This forces the current pipeline to render into a private in-memory image and returns another image handle you can fan out to several downstream operations or keep in an application cache for later reuse.

This can trade CPU time for higher memory use, so it is best reserved for intermediates you know are reused often enough to justify the retained pixels.

If a pipeline includes a large resize, do it near the start. After that, apply area operations such as sharpening, then point operations.

This reduces the amount of pixel data that later stages need to touch.

ol.vips starts from a secure default: libvips operations marked as untrusted are blocked during initialization. If you handle untrusted data, keep v/set-block-untrusted-operations! set to true unless you have a specific trusted-input path that needs those loaders.

If you need direct control over that default, use v/set-block-untrusted-operations!. Passing true restores the default secure posture, and passing false allows operations libvips has marked as untrusted.

libvips also has a lower-level class-hierarchy blocker, exposed as v/set-operation-block!. This lets you block broad families of operations and selectively re-enable the subset you trust. For example, to allow only JPEG loaders:

After those calls, libvips will only load JPEGs from the foreign-loader hierarchy. This is useful when you need tighter runtime control without building a custom libvips binary.

If you need tighter control over which loaders are present at all, prefer shipping a custom libvips build and loading it with -Dol.vips.native.preload instead of relying on a broader system installation.

See also: Security Policy.

Open the image, inspect cheap metadata first, and reject inputs that are too large or unsuitable for your main pipeline.

This is especially useful for defending against decompression bombs and for keeping progressive or interlaced inputs away from latency-sensitive paths. In practice that usually means checking v/width, v/height, and v/field before you start expensive work.

On glibc-based Linux systems, long-running multithreaded image workloads can benefit from an alternative allocator such as jemalloc. The default allocator often performs poorly for long-running, multithreaded processes with frequent small allocations, and switching allocators can reduce the off-heap footprint of the JVM when using libvips.

This is an operating environment concern rather than an ol.vips API setting. On Linux that usually means configuring LD_PRELOAD before launching the JVM, not changing anything inside your image pipeline.

The jemalloc project is also in a somewhat unsettled state. See this postmortem for background, and Facebook’s fork for one possible continuation point.

Musl-based Linux systems and non-Linux runtimes are generally less affected by this specific issue.

For image proxy workloads that process many unrelated images, the libvips operation cache is often not useful. Disable it entirely with v/disable-operation-cache!:

The cache is more useful when the same or very similar operation graphs are reused repeatedly in one process, for example a service that applies a small set of common transforms over and over. In that kind of workload, the defaults may be fine and you may not want to touch them.

When you do need to tune it, think about the three limits separately:

Tune the cache limits directly like this:

v/operation-cache-settings reports the current libvips cache limits and the current cache size. v/tracked-resources reports libvips tracked memory, highwater memory, allocation count, and tracked file count.

Those tracked counters are useful for observing trends, but they only include resources libvips tracks itself. Memory or file descriptors used inside external libraries may not be reflected there, so treat them as a lower bound rather than a complete process-wide accounting.

This is an ol.vips-specific deployment concern. The main library is small, but the companion native jars contain the bundled libvips binaries and their support libraries for a specific platform. Those jars are usually the largest part of an ol.vips deployment artifact.

If you know the production target in advance, prefer packaging only the one native companion jar that matches that runtime platform. For example, a Linux x86-64 glibc deployment usually only needs com.outskirtslabs/vips-native-linux-x86-64-gnu on the classpath.

Including several platform jars is useful for development, shared tooling, or distributing a generic application bundle. But for a single-platform deploy it usually just makes the image, container layer, or classpath larger without adding runtime value, since ol.vips will only load the bundle that matches the detected target platform.

If possible, build separate deployment artifacts per target platform and keep each one trimmed to the matching native dependency set.