webp
Convert images to WebP (quality 80) and delete the originals unless
--keepis used, optionally updating image names in a database
- Command:
/go/webp - Category: Files and media
- Required arguments:
<domain|directory|file|all> - Output: One progress line per image
- Last updated: 2026-11-20
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:
- finds
.jpg,.jpeg,.png,.gif, and.bmpfiles in a site, a folder, or every account - creates a
.webpfile next to each one, at quality 80 - deletes the original once the
.webpfile exists, unless you pass--keep - can rename the images in a database table (
Image.ImageName) to match
[!WARNING]
- Originals are deleted by default. Use
--keepuntil you are sure.- Links are not updated. Pages, templates, CSS, and most CMS databases still point to the old
.jpgor.pngnames, so deleting the originals breaks those images. Only the specialImagetable described below is updated.- The database is updated even if a conversion failed. Rows then point to
.webpfiles that do not exist.- Take a backup first with
backuporsnapshot.
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
- Appends a timestamped line with the arguments to
/var/log/go/webp.log. - Reads the MariaDB root password from the GoAdmio configuration.
- Works out what to search (see How the first argument is read).
- Takes the database name from the second argument, unless it contains
--. - Lists every
.jpg,.jpeg,.png,.gif, and.bmpfile under the target. - For each file, prints a progress line and runs
cwebp -q 80, writing<name>.webpbeside it. - If
<name>.webpnow exists and--keepwas not passed, deletes the original. - 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
- Converting
allchanges every account, but the database argument updates only one database. - The command never skips a file that already has a
.webpcopy. It converts again and replaces it. - With
--keep, running the command again converts every image again. - The MariaDB root password is passed on the command line, so it can be seen briefly in the process list.
- Paths with spaces are not handled safely in the search and in the delete step.
- To shrink images instead of converting them, see
img.
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 |