BytCrush

FAQ and troubleshooting

Frequently asked questions

Are my images uploaded anywhere?

No. All compression and conversion runs on your own server, with PHP's Imagick or GD extension. There are no API keys, quotas or monthly limits. See Privacy and data.

Where are my originals?

In a private folder inside wp-content/uploads/ named bytcrush-backups- plus a random code unique to your site, mirroring your uploads folder. Settings → Keep original images shows the exact name. See Backups and restoring.

Does my server support it?

BytCrush needs the Imagick (preferred) or GD PHP extension. BytCrush → Settings → Next-gen formats shows whether your server can create WebP and AVIF, and the dashboard warns you if neither extension is available.

Which PHP and WordPress versions are supported?

WordPress 5.3 to 7.1 and PHP 7.2 to 8.5. If the server's PHP is older than 7.2, the plugin pauses itself and shows a notice in wp-admin; your images are untouched. WebP needs an image library built with WebP support. AVIF needs PHP 8.1 or newer with GD, or Imagick with AVIF support.

Imagick or GD: what's the difference?

BytCrush uses Imagick when it's available and can write JPEGs, and GD otherwise. Both produce the same formats, but:

Imagick GD
Colour profile kept Yes No, GD writes no metadata at all
JPEG quality capped at the source's own Yes No, the source quality can't be read
Ultra palette PNGs (Pro) Yes No
Photos rotated upright from EXIF Yes Only if PHP's exif extension is installed

The library in use is shown on the dashboard (Engine:) and in Settings.

Which images are optimized?

JPEG, PNG, WebP and GIF images in the Media Library, and every size WordPress generated for them:

  • JPEG, PNG and WebP files are recompressed in place, in the same format and at the same address;
  • GIFs keep their file and get WebP and AVIF copies;
  • animated GIFs and animated PNGs are skipped: Animated images are left untouched.

Images that aren't in the Media Library, such as theme files, aren't optimized.

Will my images look worse?

The default Balanced level is tuned for no noticeable quality loss. For zero visible change, choose Gentle. Whatever the level:

  • JPEG quality is never raised above the original's;
  • a file is never replaced by a bigger one;
  • WebP and AVIF copies are only kept when they're smaller.

You can restore any image's original.

I use Nginx.

Use the default Picture tags delivery method. It works on every server. Server rewrite relies on .htaccess files, which Nginx ignores. See Delivery.

How do I exclude an image from picture-tag delivery?

Add the class no-bytcrush or the attribute data-bytcrush-skip to the <img> tag. See Delivery.

Why do some images have no WebP copy?

A copy is only kept when it's smaller than the optimized original. That's common for small thumbnails and for PNGs that already compress well. WebP images don't get a WebP copy, since they already are one. They can get an AVIF copy.

Does it work with my lazy-load plugin?

Picture tags handle lazy-load plugins that move the real image address into data-src, data-lazy-src or data-original. See Delivery.

Does it slow down uploads?

Uploads are optimized during the upload request, right after WordPress creates the image sizes, so they take a little longer. To skip that, switch off Optimize new uploads automatically and run Optimize all images from time to time instead.

What happens if I uninstall it?

Deactivating keeps everything. Deleting the plugin removes its rewrite rules. It deletes settings, statistics, WebP/AVIF copies and the stored originals only if Delete all data when uninstalling is on. See Backups.

Troubleshooting

"No image library found."

PHP has neither Imagick nor GD, so nothing can be optimized. Ask your host to enable the Imagick or GD PHP extension. Images that were tried show This server has neither Imagick nor GD installed.

"Folder permissions need fixing."

The web server can't write to your uploads folder, or to the backup folder while backups are on. BytCrush tests this with a real write before a bulk run starts, and doesn't change anything if it fails. The message names the folders.

This usually happens when the folders were created by another system user, for example WP-CLI run as root. Make the folders writable by the web server user (on most hosts: owned by the same user as the rest of wp-content/uploads), then try again.

If only some year/month folders are affected, the dashboard says Some folders will be skipped. instead. The rest of the library is optimized.

"Could not back up …, so nothing was changed."

The original couldn't be copied to the backup folder, so BytCrush left the image alone. The message gives the reason, usually an unwritable folder or a full disk. Fix it and click Retry all. If you have your own backups and are short of space, you can switch Keep original images off.

"Processing was interrupted. The server ran out of memory or time on this image."

PHP stopped while working on this image, usually because it's very large. Before each image BytCrush raises PHP's memory limit as far as WordPress allows for image work, and asks for up to 5 minutes. Some hosts don't allow either. Options:

  • ask your host for a higher PHP memory limit;
  • keep Resize oversized originals on, so huge camera photos are scaled down;
  • click Retry all. The image may succeed on a quieter moment.

"Paused after 10 failures in a row."

Ten images in a row failed, which points to a site-wide problem rather than bad images: a full disk, wrong permissions, or the server running out of memory. The rest of the message is the last error. Fix the cause and click Resume.

"The server stopped responding. The bulk run has been paused."

The dashboard tab couldn't reach your server three times in a row: a timeout, a lost connection or a server error. Click Resume to continue. If it keeps happening, switch on Optimize in the background.

"Your server is blocking background requests, so this tab is doing the work."

Background runs work by your server sending a request to itself. Some hosts, firewalls and security plugins block that. The run still works, but the tab must stay open. Ask your host to allow requests from the server to its own wp-admin/admin-ajax.php.

Create AVIF versions is greyed out

The AVIF badge in Settings is marked as unavailable: your image library has no AVIF encoder. You need PHP 8.1 or newer with GD built with AVIF support, or Imagick with AVIF support. Ask your host. WebP still works, and is supported by every modern browser.

The same applies to WebP: if Create WebP versions is greyed out, the image library was built without WebP support.

"Animated images are left untouched."

The image is an animated GIF or PNG. BytCrush skips it entirely, rather than flattening it to one frame.

"Already converted to AVIF by another plugin, so there is nothing left to optimize."

Another plugin, such as Modern Image Formats, has already replaced the file with an AVIF while WordPress still records it as a JPEG. BytCrush skips it.

"The image file is missing from the server."

The Media Library entry exists, but its file doesn't. This often happens after a migration that didn't copy all uploads. Restore the file, or delete the entry.

"Some sizes skipped" in the Media Library

The image was optimized, but some of its sizes or copies failed. Hover the tag to see why. If every file fails, the image is marked Failed instead.

Images still load as JPEG or PNG on my site

  1. Check that the image is optimized and has a WebP or AVIF tag in the Media Library's BytCrush column.
  2. Check Settings → Delivery method isn't Off.
  3. Clear your page cache and any CDN cache.
  4. With Picture tags, CSS background images and images outside the uploads folder can't be converted. On Apache or LiteSpeed, Server rewrite covers CSS backgrounds.
  5. With Server rewrite, check that the yellow warning on the Settings screen isn't showing, and that your server is really Apache or LiteSpeed.

A photo appears rotated after optimizing

BytCrush rotates photos upright before removing metadata. With GD, that needs PHP's exif extension. Without it, a photo that relied on its EXIF orientation can lose it. Use Restore original, then ask your host for the exif extension or for Imagick.

Colours look slightly different after optimizing

On GD, files lose their colour profile, which can shift colours in photos taken in a wide colour space. Imagick keeps the profile. Restore the image and ask your host for Imagick.

Pro features are still locked after buying

Install the Pro zip from your purchase email, not the free version, and activate your license when asked. The badge next to BytCrush in the header must say Pro. See Licensing.

The page audit says it couldn't open the page

The audit loads the page in a frame inside wp-admin. A security plugin sending X-Frame-Options, or a redirect to another domain, prevents that. Only pages on your own site can be scanned, and a scan gives up after 45 seconds.

Still stuck?

Contact support via warcal.dev/contact. Include:

  • your WordPress and PHP versions;
  • the image library shown on the dashboard (Engine:);
  • the exact message shown for the image.

Pro customers get priority support.