Shrink PDF files in place with Ghostscript, for one domain, folder, file, or all of /home
- Command:
/go/pdf - Category: Site files
- Required option: A domain, path, or
all - Output: One progress line per PDF; the PDFs themselves are replaced
- Last updated: 2026-11-21
On this page: Overview · Quick start · Syntax · Options · Output · Examples · Troubleshooting · Details · See also
Overview
/go/pdf finds PDF files and recompresses each one with Ghostscript. A file is replaced only if the compressed copy is smaller, so no PDF ever gets bigger. Each file keeps its original timestamps.
You can point it at:
- a domain (its
wwwfolder) - any folder or a single PDF file
all, which means every PDF under/home
You can also limit the run to files whose names start with certain letters, and choose a stronger, lower-quality compression with --screen.
[!WARNING] The original PDF is replaced, and no backup is kept. Compression reduces image quality and can invalidate digital signatures or remove some interactive features, such as form fields. Test on one file first, and make sure you have a backup.
The command needs Ghostscript (gs), which package installs. Run it as root: parts of it don't use sudo.
Quick start
# Compress every PDF in a domain's www folder
/go/pdf example.com
Syntax
/go/pdf <target> [prefix] [--screen]
/go/pdf <target> --md5 [--skip log]
| Form | Behavior |
|---|---|
/go/pdf <target> |
Compresses every PDF found at the target. |
/go/pdf <target> <prefix> |
Compresses only PDFs whose file names start with prefix. |
/go/pdf <target> --screen |
Uses the smaller, lower-quality screen setting. |
/go/pdf <target> --md5 |
Starts 16 background runs, one for each starting character a to f and 0 to 9. See The --md5 option. |
Every run is recorded in /var/log/go/pdf.log, with the time and the arguments you passed.
Options
Target
The first argument says where to look. The command uses the first rule that matches.
| Target | Meaning |
|---|---|
| An existing file or folder path | That file, or every PDF inside that folder, including subfolders. |
all |
Every PDF under /home, including mail folders and anything else stored there, not only www folders. |
| A domain name | The PDFs in /home/<domain>/www. |
If nothing matches, the command prints <target> does not exist and exits with status 1.
Other options
| Option | Required | Default | Notes |
|---|---|---|---|
prefix |
No | — | The second argument. Only PDFs whose names start with it are processed, for example a matches a1.pdf. Case-sensitive. Ignored if it starts with --. |
--screen |
No | Off | Uses Ghostscript's /screen setting (smallest files, lowest image quality) instead of /ebook. |
--md5 |
No | Off | Splits the work into 16 background runs by first character of the file name. See The --md5 option. |
--skip log |
No | Off | Used with --md5. Skips any starting character that already has a log file. Write it as two words. |
Only files named *.pdf in lowercase are found. Files ending in .PDF are ignored.
Output
For each compressed PDF the command prints one line. The percentage is the new file's size compared with the original, so a lower number means more savings.
[1/12] Resizing /home/example.com/www/docs/a.pdf (42%)...
[2/12] Resizing /home/example.com/www/docs/b.pdf (Same Size)...
| Message | Meaning |
|---|---|
Resizing <file> (<n>%)... |
The compressed copy was smaller and replaced the original. |
Resizing <file> (Same Size)... |
The compressed copy was not smaller (the same size or larger), so the original was kept. |
<target> does not exist |
The first argument matched nothing. Exit status 1. |
When only one file is found, the [n/total] prefix is left out. If no PDFs are found, the command prints nothing.
Log
Each run appends one line to /var/log/go/pdf.log:
[Nov 21 12:00:00]# pdf example.com
With --md5, each background run also writes its own log, described below.
Examples
# Every PDF in a domain's www folder
/go/pdf example.com
# Only PDFs whose names start with "a"
/go/pdf example.com a
# Smaller files, lower quality
/go/pdf example.com --screen
# One folder
/go/pdf /home/example.com/www/uploads
# A single file
/go/pdf /home/example.com/www/uploads/report.pdf
# Every PDF on the server
/go/pdf all
# A large site, in 16 background runs
/go/pdf /home/example.com/www --md5
# Run the missing runs again, keeping those that already have a log
/go/pdf /home/example.com/www --md5 --skip log
Troubleshooting
An empty result is not an error: it means no matching PDFs were found.
| Symptom | Likely cause | Fix |
|---|---|---|
<target> does not exist |
The first argument isn't a file, folder, all, or a domain with a /home/<domain>/www folder. |
Check the spelling or pass a full path. |
| Nothing is printed | No *.pdf files at the target, or none match the prefix. |
Check the folder. Files named .PDF are not found. |
gs: command not found |
Ghostscript isn't installed. | Run package, then try again. |
| A file is skipped or an error appears for a path with spaces | File and folder names with spaces aren't handled. | Rename the file, or process its parent folder after renaming. |
Many files say (Same Size) |
They are already optimized, so the compressed copy was not smaller. | None. The originals are untouched. |
| Compressed files are now owned by root, or can't be replaced over FTP | The new file is created by the user running the command, normally root. | Run fix for the account. |
| Quality is too low | --screen was used, or the default is too strong for these files. |
Restore the originals from a backup with restore or snapshot. |
The server is slow during --md5 |
Sixteen Ghostscript processes run at once. | Wait, or run one character at a time, for example /go/pdf example.com a. |
--md5 returned at once with status 1 |
Expected. See The --md5 option. |
Follow progress in the log files. |
Details
The --md5 option
Despite its name, --md5 does not calculate any checksum. It is a way to split a big job across 16 background runs. This suits folders whose file names start with a hexadecimal character, such as files named by their MD5 hash.
/go/pdf <target> --md5
For each of the characters a b c d e f 0 1 2 3 4 5 6 7 8 9, the command starts a separate background run equivalent to /go/pdf <target> <character>, and then exits with status 1.
| Behavior | Detail |
|---|---|
| Log files | Each run writes to /var/log/go/pdf/<domain>-<character>.log. The domain is read from the third part of the path, so use a full path such as /home/example.com/www. |
| Files processed | Only PDFs whose names start with one of those 16 lowercase characters. Other names are not processed. |
| Skipping | With --skip log, a character is skipped if its log file already exists. This lets you resume a run, but it also skips finished characters. Delete a log to process that character again. |
| Quality | The background runs don't receive --screen, so they always use the default /ebook setting. |
| Progress | Watch a run with tail -f /var/log/go/pdf/<domain>-<character>.log. |
What happens to each file
| Step | Action |
|---|---|
| 1 | Ghostscript writes a compressed copy next to the original as <file>.bak, using /ebook (default) or /screen. |
| 2 | The original file's timestamps are copied onto the copy. |
| 3 | The sizes are compared. |
| 4a | If the copy is smaller, the original is deleted and the copy takes its name. |
| 4b | Otherwise, the copy is deleted and the original is left as it was. |
| Setting | Ghostscript preset | Image resolution | Use |
|---|---|---|---|
| Default | /ebook |
About 150 dpi | A balance of size and quality. |
--screen |
/screen |
About 72 dpi | Smallest files, lowest quality. |
flowchart TD
A["pdf target [prefix]"] --> B{"Target found?"}
B -- "No" --> X["Print does not exist, exit 1"]
B -- "Yes" --> C{"--md5?"}
C -- "Yes" --> D["Start 16 background runs, one per first character, exit 1"]
C -- "No" --> E["Find the *.pdf files, filtered by prefix"]
E --> F["For each file: Ghostscript writes file.bak"]
F --> G{"Copy smaller?"}
G -- "Yes" --> H["Replace the original"]
G -- "No" --> I["Delete the copy, keep the original"]
See also
| Command | Description |
|---|---|
img |
Shrink large images (over 512 KB) in place so they fit within 800×600 pixels |
webp |
Convert images to WebP format |
fix |
Reset ownership and permissions for one account or all accounts |
package |
Upgrade system packages, then install any missing GoAdmio base packages and tools |
snapshot |
Back up, list, check, restore, and delete restic snapshots of hosting accounts |
restore |
Restore accounts, databases, SSL certificates, or folders from local or remote GoAdmio backups |