Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Kirby WebP

Release License Issues

This plugin generates WebP images alongside your uploaded JPGs & PNGs - so you don't have to.

Table of contents

What is it good for?

Absolutely .. smaller image size:

WebP is a method of lossy and lossless compression that can be used on a large variety of photographic, translucent and graphical images found on the web. The degree of lossy compression is adjustable so a user can choose the trade-off between file size and image quality. WebP typically achieves an average of 30% more compression than JPEG and JPEG 2000, without loss of image quality (see Comparative Study).

Google Developers

Current browser support for WebP images is decent (Chrome, Opera & most mobile browsers), although heavily depending on your target region (ranging from North America (60%) & Europe (65%) to over 80% in Africa & South America).

For further information, including criticism, check out its Wikipedia article. That being said, another interesting approach gearing towards the replacement of JPEG is Fabrice Bellard's "Better Portable Graphics" (BPG) format.

Getting started

Use one of the following methods to install & use kirby-webp:


composer require S1SYPHOS/kirby-webp:dev-composer

Git submodule

If you know your way around Git, you can download this plugin as a submodule:

git submodule add site/plugins/kirby-webp

Clone or download

  1. Clone or download this repository.
  2. Unzip / Move the folder to site/plugins.

Activate the plugin

Activate the plugin with the following line in your config.php:

c::set('plugin.kirby-webp', true);


After uploading some images, you are now officially ready to serve their newly generated WebP versions.


If you're using Apache as your webserver, add the following lines to your .htaccess:

<IfModule mod_rewrite.c>
  RewriteEngine On

  # Checking for WebP browser support ..
  RewriteCond %{HTTP_ACCEPT} image/webp

  # .. and if there's a WebP version for the requested image
  RewriteCond %{DOCUMENT_ROOT}/$1.webp -f

  # Well, then go for it & serve WebP instead
  RewriteRule (.+)\.(jpe?g|png)$ $1.webp [T=image/webp,E=accept:1]

<IfModule mod_headers.c>
  Header append Vary Accept env=REDIRECT_accept

<IfModule mod_mime.c>
  AddType image/webp .webp


If you're using NGINX as your webserver, add the following lines to your virtual host setup (for more information, go here or there):

// First, make sure that NGINX' `mime.types` file includes 'image/webp webp'
include /etc/nginx/mime.types;

// Checking if HTTP's `ACCEPT` header contains 'webp'
map $http_accept $webp_suffix {
  default "";
  "~*webp" ".webp";

server {
  // ...

  // Checking if there's a WebP version for the requested image ..
  location ~* ^.+\.(jpe?g|png)$ {
    add_header Vary Accept;
    // .. and if so, serving it
    try_files $1$webp_ext $uri =404;


Change kirby-webp options to suit your needs:

Option Type Default Description
plugin.kirby-webp.hooks Array ['upload'] Contains all panel.file.* hooks WebP generation should be applied to (allowed values are upload, update, rename and replace).
plugin.kirby-webp.quality Integer 90 Defines WebP image quality (ranging from 0 to 100).
plugin.kirby-webp.stripMetadata Boolean true Optionally enables / disables transfer of JPEG metadata onto the WebP image.
plugin.kirby-webp.convertedImage Boolean true Optionally enables / disables output of converted image (false results in text output about the conversion process).
plugin.kirby-webp.serveOriginalOnFail Boolean true Defines behavior in case all converters fail - by default, the original image will be served, whereas false will generate an image with the error message.
plugin.kirby-webp.converters Array ['gd', 'cwebp'] Defines the desired order of execution for all supported converters (allowed values are imagick, cwebp, gd and ewww). Note that this only changes their order, but doesn't remove any of them.


Despite stating that An unexpected error occurred, WebP generation after renaming / updating images works - replace doesn't work at all .. PRs are always welcome 🍾

Because of that, only upload is included by default. If you wish to investigate this further and / or don't care too much about the errror, go ahead with c::set('plugin.webp.actions', ['upload', 'update', 'rename', 'replace']); in your config.php.

Credits / License

kirby-webp is based on Bjørn Rosell's PHP library webp-convert library. It is licensed under the MIT License, but using Kirby in production requires you to buy a license. Are you ready for the next step?

Special Thanks

I'd like to thank everybody that's making great software - you people are awesome. Also I'm always thankful for feedback and bug reports :)