PHPackages bitbetter/kirby-libvips - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. bitbetter/kirby-libvips ActiveKirby-plugin bitbetter/kirby-libvips ======================= Fast, memory-efficient libvips thumbnail driver for Kirby CMS with in-process (php-vips FFI) and CLI backends v1.0.0(1mo ago)1164↑33.3%MITPHPPHP >=8.1 Since Jul 18Pushed 1mo agoCompare [ Source](https://github.com/bitbetterde/kirby-libvips)[ Packagist](https://packagist.org/packages/bitbetter/kirby-libvips)[ RSS](/packages/bitbetter-kirby-libvips/feed)WikiDiscussions master Synced 2w ago READMEChangelogDependencies (1)Versions (2)Used By (0) Kirby libvips thumbnail driver ============================== [](#kirby-libvips-thumbnail-driver) A thumbnail ([Darkroom](https://github.com/getkirby/kirby/tree/main/src/Image/Darkroom)) driver for [Kirby CMS](https://getkirby.com) that generates thumbs with [libvips](https://www.libvips.org) — in-process via php-vips (FFI) or by shelling out to the `vipsthumbnail` CLI. Compared to GD or ImageMagick, libvips is faster and uses a fraction of the memory — especially noticeable with large source images or bulk thumb generation. Resize, crop (center, positional, panel focus points, smartcrop), `blur`, `grayscale` and `sharpen` are all supported. Requires **Kirby 4 or 5**, **PHP ≥ 8.1** and **libvips ≥ 8.15** installed on the server (`apt install libvips-tools`, `brew install vips`, …). Out of the box the plugin shells out to the `vipsthumbnail` and `vips` binaries — no PHP extension needed. If [php-vips](https://github.com/libvips/php-vips) is installed (`composer require jcupitt/vips`), the plugin automatically switches to in-process generation via FFI, which eliminates the ~60 ms process-spawn cost per thumb and makes small thumbs faster than GD. Installation ------------ [](#installation) ``` composer require bitbetter/kirby-libvips ``` Or copy this repository to `/site/plugins/kirby-libvips`. For the fast in-process backend (recommended), additionally install php-vips: ``` composer require jcupitt/vips ``` The plugin picks it up automatically — no configuration needed. Without it, the plugin uses the `vipsthumbnail`/`vips` binaries. Usage ----- [](#usage) ``` // site/config/config.php return [ 'thumbs' => [ 'driver' => 'vips', ], ]; ``` That's it. The plugin registers itself as a proper Darkroom driver, so Kirby's whole thumb pipeline (media jobs, `srcset()`, focus cropping, format conversion via `thumbs.format`) works unchanged. Options ------- [](#options) All options go into the `thumbs` config array: OptionDefaultDescription`backend``auto``ffi` (in-process php-vips), `cli` (binaries), or `auto` to pick FFI when available`bin``vipsthumbnail`Path to the `vipsthumbnail` binary (CLI backend)`vipsBin``vips`Path to the `vips` binary (used for exact focus crops)`quality``90`Output quality (JPEG/WebP/AVIF/…)`interlace``false`Progressive JPEGs / interlaced PNGs`strip``true`Strip all metadata (EXIF, ICC, XMP) from thumbs`profile``'srgb'`Convert to this ICC profile before stripping (`false` to disable)`smartcrop``false`Content-aware cropping for plain center crops: `'attention'` or `'entropy'``autoOrient``true`Auto-rotate according to EXIF orientation`threads``1`Number of threads vips may use per job``` return [ 'thumbs' => [ 'driver' => 'vips', 'quality' => 85, 'interlace' => true, 'smartcrop' => 'attention', 'bin' => '/usr/local/bin/vipsthumbnail', ], ]; ``` Cropping behavior ----------------- [](#cropping-behavior) - `$file->crop(300, 200)` — center crop (or content-aware, if `smartcrop` is configured) - Positional crops (`'top left'`, `'bottom'`, …) and **panel focus points** (`'45% 30%'`) are honored exactly, matching the behavior of Kirby's built-in drivers. EXIF-rotated images are handled correctly (the crop is applied in display space). - With `smartcrop: 'attention'`, plain center crops use libvips' [smartcrop](https://www.libvips.org/API/current/libvips-conversion.html#vips-smartcrop) to find the most interesting region — explicit focus points still win. Effects ------- [](#effects) `blur`, `grayscale` and `sharpen` are fully supported: ``` $file->blur(10); $file->grayscale(); // also: ->bw() $file->sharpen(50); $file->thumb(['width' => 480, 'grayscale' => true, 'blur' => 4, 'sharpen' => 50]); // combined in one job ``` They are parameter-matched to Kirby's ImageMagick driver (`gaussblur` with the same sigma, `colourspace b-w`, `sharpen --sigma amount/100`), so switching drivers doesn't change the look. Note that GD's blur is much weaker than IM/vips at the same value — that inconsistency exists between Kirby's built-in drivers too. With the FFI backend the whole pipeline (shrink, crop, effects, encode) fuses in memory — no subprocesses, no intermediate files. With the CLI backend, effects run as additional `vips` operations on the already-shrunk intermediate, so each adds one process spawn but little actual work. Backends -------- [](#backends) - **`auto`** (default): uses php-vips (FFI) when `jcupitt/vips` is installed and PHP's FFI extension is usable, otherwise the CLI binaries. Detection runs once per request and fails safe to CLI. - **`ffi`**: forces php-vips. ~5–15 ms per thumb warm; the one-time FFI/libvips initialization (~150 ms) is paid once per PHP-FPM worker, not per thumb. If FFI is blocked on your setup, set `ffi.enable = true` in php.ini. - **`cli`**: forces the `vipsthumbnail`/`vips` binaries. No PHP requirements at all, but each thumb pays a fixed process-spawn cost (~10–70 ms depending on platform). Both backends produce identically sized, visually identical output — `backend` only changes how fast you get it. Performance ----------- [](#performance) All numbers measured through Kirby's real thumb pipeline (`Darkroom->process()` on a copied file, exactly what the media route does) with Kirby 5.5.2, libvips 8.18.4, ImageMagick 7.1.2, PHP 8.5 on Apple Silicon; fastest of 3 runs, warm. Your absolute numbers will differ — the ratios are the point. ### Speed [](#speed) GDImageMagickvips CLIvips FFI1000 px source → resize 480 px10.5 ms24.1 ms91.4 ms**7.8 ms**1000 px source → focus crop19.1 ms25.5 ms158.3 ms**3.7 ms**1000 px source → gray + blur + sharpen35.1 ms30.6 ms313.4 ms**12.6 ms**6000 px source → resize 480 px204.7 ms154.7 ms121.1 ms**37.9 ms**6000 px source → srcset (4 widths)887.6 ms1320.4 ms735.3 ms**219.8 ms**What that means in practice: - **A gallery page requesting 50 thumbs** of fresh 17 MP camera uploads: ~1.9 s of CPU with the FFI backend vs. ~10 s with GD — and if each image also gets a 4-width `srcset()`, ~11 s vs. ~44 s. - **Small, already-downscaled sources** (CMS re-uploads, screenshots): FFI is still the fastest option; the CLI backend is the *slowest* here because every job pays a fixed ~60–80 ms process spawn regardless of image size. If you can't use FFI and your sources are small, GD is legitimately fine. - Thumbs are generated once and cached in `/media`, so these costs apply on first generation (uploads, cache busts, deploys with cleared media) — which is exactly when dozens of jobs hit PHP at once. ### Memory [](#memory) Peak RSS generating one 480 px thumb from the 6000 px source: GDImageMagickvips CLIvips FFI106.5 MB240.9 MB**32.4 MB****~46 MB** on top of the PHP worker¹¹ 74 MB total for a one-shot `php` process incl. the 28 MB PHP baseline; in PHP-FPM the runtime is already resident, so the marginal cost per worker is the ~46 MB libvips share, reused across all jobs of that worker. - **GD and ImageMagick decode the full bitmap first** — memory scales with source *megapixels*, not thumb size. The 6000 × 2862 source costs GD ~68 MB for the raw bitmap before any resizing happens. libvips streams via shrink-on-load and stays near-flat regardless of source size. - **GD actually crashes on this workload:** `$file->crop(240, 240)` on the 6000 px source aborts with `Allowed memory size of 134217728 bytes exhausted` at PHP's default 128 MB `memory_limit`. The same job needs no config changes with libvips. - **Concurrency is the multiplier:** a panel page or gallery triggers many parallel media requests. Eight PHP-FPM workers generating simultaneously peak around ~850 MB with GD and ~1.9 GB with ImageMagick — vs. ~260 MB with the CLI backend or ~370 MB with FFI. On small servers this is the difference between finishing and OOM-killing. Migrating from kirby3-vipsthumbnail ----------------------------------- [](#migrating-from-kirby3-vipsthumbnail) - `thumbs.driver => 'vipsthumbnail'` still works as an alias for `'vips'`. - `blur`, `grayscale` and `sharpen` were previously ignored — they are now applied. - Panel focus points and positional crops were previously flattened to smartcrop-attention — they are now honored exactly; content-aware cropping is opt-in via the `smartcrop` option. - The `log`/`logdir` options were removed; errors now surface as exceptions including the vips error output. - `autoOrient` now defaults to `true` (matching libvips' own default and Kirby's other drivers) and no longer breaks on libvips ≥ 8.8. LLM disclosure -------------- [](#llm-disclosure) The Kirby 4/5 rewrite of this plugin — the Darkroom driver, the FFI backend, the effects support, this README and the benchmarks — was written in large part by an LLM (Claude Opus 4.8 via Claude Code), directed and reviewed by a human maintainer. What that means for you: - **Nothing here is unverified LLM output.** Every code path was exercised against a real Kirby 5.5.2 installation with an 18-case test harness: output dimensions are checked against Kirby's GD driver, EXIF-rotated sources, panel focus points, format conversion (WebP/AVIF/PNG), metadata stripping, quality settings, and paths with spaces are all covered, for both backends. - **The benchmark numbers are real measurements** from that setup (hardware and versions stated above), not estimates or vendor claims. - The plugin still ships human-auditable, dependency-light code: two PHP files you can read in ten minutes. If you find behavior that differs from Kirby's built-in drivers beyond what's documented here, that's a bug — please open an issue. Credits ------- [](#credits) Originally based on [kirby3-vipsthumbnail](https://github.com/floriankarsten/kirby3-vipsthumbnail) by Florian Karsten. Rewritten for Kirby 4/5's Darkroom API and current libvips. License ------- [](#license) MIT ### Health Score 42 — FairBetter than 88% of packages Maintenance90 Actively maintained with recent releases Popularity17 Limited adoption so far Community9 Small or concentrated contributor base Maturity42 Maturing project, gaining track record Bus Factor1 Top contributor holds 68.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 46d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/3447307?v=4)[Bitbetter](/maintainers/bitbetter)[@bitbetter](https://github.com/bitbetter) --- Top Contributors [![iskrisis](https://avatars.githubusercontent.com/u/4954323?v=4)](https://github.com/iskrisis "iskrisis (11 commits)")[![pReya](https://avatars.githubusercontent.com/u/4677417?v=4)](https://github.com/pReya "pReya (4 commits)")[![S1SYPHOS](https://avatars.githubusercontent.com/u/12161504?v=4)](https://github.com/S1SYPHOS "S1SYPHOS (1 commits)") --- Tags kirbylibvipsThumbnailskirbykirby-pluginlibvipsvips ### Embed Badge ![Health badge](/badges/bitbetter-kirby-libvips/health.svg) ``` [![Health](https://phpackages.com/badges/bitbetter-kirby-libvips/health.svg)](https://phpackages.com/packages/bitbetter-kirby-libvips) ``` ### Alternatives [getkirby/cms The Kirby core 1.5k631.0k563](/packages/getkirby-cms)[medienbaecker/kirby-modules Easily add modules to your pages 895.6k1](/packages/medienbaecker-kirby-modules)[timnarr/kirby-imagex Modern images for Kirby CMS – This plugin helps you orchestrate modern, responsive and performant images in Kirby 829.3k1](/packages/timnarr-kirby-imagex)[bnomei/kirby3-janitor Kirby Plugin for running commands like cleaning the cache from within the Panel, PHP code or a cronjob 9344.2k2](/packages/bnomei-kirby3-janitor)[johannschopplich/kirby-content-translator DeepL & AI-powered content translation for Kirby CMS 2012.1k](/packages/johannschopplich-kirby-content-translator)[bnomei/kirby3-feed Generate a Atom/JSON/RSS-Feed and XML-Sitemap from Pages-Collections 7228.9k](/packages/bnomei-kirby3-feed) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)