Contributors: ddegner Tags: avif, images, performance, media, optimization Requires at least: 6.8 Tested up to: 6.9 Stable tag: 0.4.9 Requires PHP: 8.3 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html
High-quality AVIF image conversion for WordPress — local, quality-first.
Built by a Boston photographer who needed it for their own portfolio. This plugin prioritizes image quality over everything else — no subscriptions, no external services.
- Local Processing — All conversion happens on your server. No external API calls. Works great on a shared CPU with 2GB RAM.
- Quality First — Uses LANCZOS resizing, preserves ICC color profiles, and keeps EXIF/XMP/IPTC metadata intact.
- Fully Tunable — Control quality (0–100), speed (0–10), chroma subsampling (4:2:0, 4:2:2, 4:4:4), and bit depth (8/10/12-bit).
- Smart Fallback — Serves AVIF to supported browsers, JPEG to everyone else via picture elements.
- Automatic Conversion — Convert on upload or via daily scheduled background scans.
Front end: The plugin wraps your img tags in picture elements with an AVIF source. Browsers that support AVIF load the smaller, higher-quality file — others gracefully fall back to JPEG.
Conversion: Uses ImageMagick CLI (fastest), Imagick PHP extension (high quality), or GD Library (fallback) to convert JPEGs to AVIF on upload or via background jobs.
- Upload to
/wp-content/plugins/avif-local-supportor install via Plugins → Add New - Activate the plugin
- Navigate to Settings → AVIF Local Support
- PHP: 8.3 or later
- WordPress: 6.8 or later
- Recommended: Imagick extension with AVIF-enabled ImageMagick
Manage AVIF conversions from the command line.
Show system status and AVIF support diagnostics:
wp avif status
wp avif status --format=json
Convert JPEG images to AVIF format:
wp avif convert --all
wp avif convert 123
wp avif convert --all --dry-run
Options:
<attachment-id>— Specific attachment ID to convert--all— Convert all attachments missing AVIF versions--dry-run— Show what would be converted without actually converting
Show AVIF conversion statistics:
wp avif stats
wp avif stats --format=json
View or clear conversion logs:
wp avif logs
wp avif logs --limit=50
wp avif logs --clear
Options:
--clear— Clear all logs--limit=<number>— Number of logs to show (default: 20)
Delete AVIF files for an attachment or all attachments:
wp avif delete 123
wp avif delete --all --yes
Options:
<attachment-id>— Attachment ID to delete AVIF files for--all— Delete all AVIF files in the media library--yes— Skip confirmation prompt when using --all
For more information, visit wp-cli.org.
The plugin supports three conversion engines, in order of preference:
Uses the ImageMagick command-line binary directly:
- System binary: ImageMagick 7.x built with HEIF/AVIF support (via libheif)
- No PHP extension required
- Benefits: Fastest performance, LANCZOS resizing, full metadata preservation (EXIF, XMP, IPTC, ICC)
- Typical paths:
/usr/bin/magick,/usr/local/bin/magick, or Homebrew on macOS
To verify AVIF support:
magick -list format | grep -i avif
Uses the PHP Imagick extension:
- PHP extension: imagick
- System libraries: ImageMagick built with HEIF/AVIF support (via libheif)
- Benefits: LANCZOS resizing, full metadata preservation (EXIF, XMP, IPTC, ICC), color profile handling
To install on Ubuntu/Debian:
apt install php-imagick imagemagick libheif-dev
Uses PHP's built-in GD library:
- PHP extension: gd built with AVIF support (provides imageavif on PHP 8.1+)
- Note: Some distro builds omit AVIF support; limited metadata preservation
Ensure your web server is configured to serve .avif files as image/avif.
No. AVIF files are created alongside your existing images. Your originals remain untouched.
If "Convert on upload" is enabled, uploads may take slightly longer. You can disable this and use scheduled background conversion instead.
Recommended but not required. Imagick provides the best quality and preserves metadata/color profiles. The plugin falls back to GD if unavailable.
No. Zero tracking, zero external calls. Everything runs locally.
The plugin estimates memory before processing to prevent crashes. Try switching to "ImageMagick CLI" engine, increasing PHP memory_limit, or checking "Disable memory check" in settings.
This is caused by libheif 1.12.0 crashing in LiteSpeed's restricted environment. Upgrade libheif to 1.15+ to fix. See the WordPress.org FAQ for build instructions.
LiteSpeed's open_basedir restriction prevents PHP from detecting executables outside allowed paths. The binary may still work — try setting the path manually in settings.
- Settings — Configure AVIF quality, speed, and conversion options
- Tools — Convert missing AVIFs, test conversions, bulk delete
- Status — Server capability diagnostics and library coverage
- About — Quick reference and version info
- Fix: WordPress Plugin Check compliance — proper escaping, Yoda conditions, and PHPCS ignores
- Fix: Improved uninstall cleanup with object cache awareness
- Dev: Code formatting aligned with WordPress coding standards
- Fix: Resolved logging pipeline issues where REST API couldn't retrieve logs due to
is_admin()check - Fix: Fixed upload test timeout by temporarily disabling synchronous AVIF conversion during test uploads
- Fix: Improved AJAX feedback for log operations (clear/refresh)
- Docs: Updated minimum requirements to WordPress 6.8 and PHP 8.3
- Docs: Cleaned up README header format for WordPress.org compatibility
- Docs: Removed donate link from readme
- Dev: Added WordPress stubs for improved IDE support
- Enhancement: Improved time formatting in conversion progress display (hh:mm:ss format)
- Enhancement: CLI code formatting improvements
- Fix: Corrected contributor username in readme
- Docs: Added WordPress.org metadata headers
- Docs: Updated tested up to WordPress 6.9
- Fix: Corrected "Upload & Test" status display issues (spinner visibility, status text alignment)
- Fix:
wp avif deletecommand now correctly reports success/failure counts and handles permission errors - Fix:
wp avif convertcommand output now includes count of missing AVIFs - Enhancement: Added GitHub Action for automated release creation
- Feature: Fully asynchronous "Upload & Test" conversion to prevent timeouts on large images
- Enhancement: Re-architected test conversion to use sequential polling
- Enhancement: Admin UI modularized with template-based architecture
- Optimization: Removed unused
vendorstorage and legacy dependencies, reducing plugin size - Fix: Restored robust queue rendering for test results
- Added WP-CLI commands: status, convert, stats, logs, delete
- Refactored admin interface with modular architecture
- Improved logging and environment diagnostics
- Auto-detection for ImageMagick CLI in "Auto" mode
- REST API replaces admin-ajax for better performance
- Smart -define namespace probing (heic/avif)
- Tested with WordPress 6.9
- Compatibility: Tested up to WordPress 6.9
- Major refactor: strict types, DTOs, dedicated Encoder classes
- Optimized frontend HTML parsing
- Enhanced CLI execution and error handling
- Composer support (PSR-4 ready)
- Environment variable injection for restricted PHP environments
- Original image source handling fixes
- Engine priority: CLI, Imagick, GD
- ImageMagick CLI support with auto-detection
- Memory pre-check to prevent fatal errors
- Logs panel with detailed entries
- Lightbox anchor rewriting
- Chroma subsampling and bit depth options
- Initial release with Imagick/GD support
- ICC profile preservation
- EXIF orientation handling
- Basic admin interface
See GitHub releases for complete version history.
Contributions welcome! Please submit issues and pull requests on GitHub.
GPL v2 or later — View License