GoAdmio

webp

Convert images to WebP (quality 80) and delete the originals unless --keep is used, optionally updating image names in a database

On this page: Overview · Quick start · Syntax · Arguments · Output · Examples · Troubleshooting · Details · See also


Overview

WebP images are usually much smaller than JPEG, PNG, and GIF files at similar quality, which makes pages load faster. /go/webp converts the images already on your server. It:

[!WARNING]

  • Originals are deleted by default. Use --keep until you are sure.
  • Links are not updated. Pages, templates, CSS, and most CMS databases still point to the old .jpg or .png names, so deleting the originals breaks those images. Only the special Image table described below is updated.
  • The database is updated even if a conversion failed. Rows then point to .webp files that do not exist.
  • Take a backup first with backup or snapshot.

Quick start

# Convert a site but keep the originals (safe first test)
/go/webp example.com --keep

Syntax

/go/webp <domain|directory|file|all> [database] [--keep]

Arguments

Position Argument Required Notes
1 domain, directory, file, or all Yes What to convert. See How the first argument is read.
2 database No A database whose Image table should be updated. Ignored if the argument contains --.
any --keep No Keep the original images. It works in any position.

The database must be the second argument. In /go/webp example.com --keep mydb, the second argument is --keep, so mydb is ignored.

How the first argument is read

Order Check Result
1 Is it an existing file or directory? Used as given, relative to your current folder.
2 Is it all? Searches /home, which covers every account.
3 Does /home/<value>/www exist? Searches that folder.
4 None of the above <value> does not exist and the command stops.

What gets converted

Rule Detail
Extensions .jpg, .jpeg, .png, .gif, .bmp. Lowercase only, so PHOTO.JPG is skipped.
Folders Searched recursively.
Size No limit. Small images are converted too.
Quality Fixed at 80 (lossy), including for PNG.
Output <name>.webp in the same folder, replacing any existing file of that name.

Output

[1/250] Converting /home/example.com/www/img/photo.jpg to /home/example.com/www/img/photo.webp...
Message Meaning
[<n>/<total>] Converting <file> to <file.webp>... One line per image.
<value> does not exist The first argument was not found. Exit code 1.
Errors from cwebp or MariaDB A conversion or database update failed.

There is no summary at the end, and nothing says whether a conversion worked. A failed conversion leaves the original in place.


Examples

# Convert one site and keep the originals
/go/webp example.com --keep
# Convert one folder
/go/webp /home/example.com/www/uploads --keep
# Convert one file
/go/webp /home/example.com/www/images/banner.png --keep
# Convert and delete the originals
/go/webp example.com
# Convert, delete the originals, and update the Image table in a database
/go/webp example.com example_db
# Convert every site, keeping the originals
/go/webp all --keep
# Check that the converter is installed
command -v cwebp

Troubleshooting

Symptom Likely cause Fix
<value> does not exist No such file or folder, and no /home/<value>/www. Check the spelling, or pass a full path.
cwebp: command not found WebP support is not installed. Nothing is converted. Install it with installwebp.
Images are broken after converting The originals were deleted, but pages and the database still use the old names. Restore from a backup. Next time use --keep, and update the references or add a web server rule that serves the .webp files.
An image is missing or shows the wrong picture Two files shared a base name, for example photo.jpg and photo.png, so both became photo.webp and the second replaced the first. An existing photo.webp is also replaced. Restore from a backup. Rename files that share a base name before converting.
GIF or BMP files were not converted Many cwebp builds cannot read these formats. The originals are kept. Convert GIFs with gif2webp, which also keeps animation.
An animated GIF lost its animation cwebp writes a single still frame. Restore it and use gif2webp.
MariaDB says the table Image does not exist The database update only works for a table named Image with an ImageName column. Leave out the database argument.
Rows point to missing .webp files The database update runs even when some or all conversions failed. Fix the rows, or restore the database from a backup.
The database argument had no effect It was not the second argument, or it started with --. Put it second, as in /go/webp example.com example_db.
Colors or detail look worse The quality is fixed at 80 and lossy. Keep the originals with --keep, or convert by hand with other settings.
Files with spaces in the name Deleting the original uses an unquoted path, so the original may stay, or a different path may be removed. Rename such files before converting.
The new .webp files are owned by root cwebp runs as the user who started the command. Run fix for the domain.
PHOTO.JPG was not converted Only lowercase extensions are matched. Rename the extension, or convert it by hand.
High CPU for a long time Files are converted one after another. Run at a quiet time.

Details

What it does

flowchart TD
    A["/go/webp target [database] [--keep]"] --> B["Append the command to /var/log/go/webp.log"]
    B --> C{"Target found?"}
    C -- "No" --> D["Print error and exit"]
    C -- "Yes" --> E["List image files in the target"]
    E --> F["For each file: cwebp -q 80 to name.webp"]
    F --> G{"name.webp exists and no --keep?"}
    G -- "Yes" --> H["Delete the original"]
    G -- "No" --> I["Keep the original"]
    H --> J["Next file"]
    I --> J
    J --> K{"Database given?"}
    K -- "Yes" --> L["Update Image.ImageName to .webp"]
    K -- "No" --> M["Done"]

Steps in order

  1. Appends a timestamped line with the arguments to /var/log/go/webp.log.
  2. Reads the MariaDB root password from the GoAdmio configuration.
  3. Works out what to search (see How the first argument is read).
  4. Takes the database name from the second argument, unless it contains --.
  5. Lists every .jpg, .jpeg, .png, .gif, and .bmp file under the target.
  6. For each file, prints a progress line and runs cwebp -q 80, writing <name>.webp beside it.
  7. If <name>.webp now exists and --keep was not passed, deletes the original.
  8. If a database was given, updates its image names (see below).

Database update

When a database is given, these statements run on the table Image, column ImageName, for every row, whether or not the matching file was converted:

Replaces With
.jpeg .webp
.jpg .webp
.png .webp
.gif .webp
.bmp .webp

UPDATE IGNORE is used, so rows that would break a unique key are skipped without a message. The replacement matches the text anywhere in the name, not only at the end.

This is not for WordPress or other CMS databases. Those store image links in many tables and in page content.

Notes


See also

Command Description
installwebp Install WebP support in GoAdmio
img Resize images on a GoAdmio server
img-out-db Remove images not found in the MySQL database
pdf Compress PDF files in a site directory
backup Create a backup for all GoAdmio accounts (local and remote)
snapshot Restic-based per-domain snapshot backup and restore
fix Fix GoAdmio file and folder permissions
recover Restore a deleted account from its latest snapshot