Installing ImageMagick + Imagick for PHP 8.3 on Ubuntu (20.04 / 22.04 / 24.04) with Reliable AVIF + WebP Output

If your WordPress plugin uses Imagick to generate AVIF and WebP, most “it works on my server but not on the customer’s” failures come down to one thing: Imagick can only write formats that the underlying ImageMagick build can write. That means your real source of truth is always:

magick -list format (does ImageMagick list AVIF/WEBP, and are they writable?)
php --ri imagick (which ImageMagick version and build did your PHP extension link against?)

This guide gives you a predictable, developer-grade setup across Ubuntu LTS versions by building ImageMagick 7 with the right delegates (AVIF via libheif, WebP via libwebp) and then installing a PHP 8.3-compatible Imagick extension release.

What Ubuntu ships by default (and why you shouldn’t blindly trust it for AVIF)

Ubuntu LTS releases typically ship ImageMagick 6 (IM6) in the standard repos, with different patch levels:

Ubuntu 20.04 (Focal) IM6 baseline can be checked in the package record on the official Ubuntu package pages (for example the Focal imagemagick listing on Launchpad).
Ubuntu 22.04 (Jammy) IM6 baseline commonly includes 6.9.11.x, which matters because Jammy has a well-documented AVIF/HEIC alpha bug.
Ubuntu 24.04 (Noble) IM6 baseline commonly includes 6.9.12.x, which is improved, but still depends on how delegates are built.

A concrete example of why this matters: on Ubuntu 22.04, transparent images converted to AVIF/HEIC can render with a black background, tracked as Launchpad bug #1980124: https://bugs.launchpad.net/bugs/1980124. A related Debian report confirms a fix in a later ImageMagick patch level: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1040307. If your plugin must handle PNG alpha correctly, the safest approach is to run a newer ImageMagick build rather than relying on the Jammy IM6 baseline.

Target outcome

When you’re done, these commands should show that AVIF/HEIC and WEBP are writable and that PHP Imagick is linked to the ImageMagick you intended:

magick -version
magick -list format | egrep 'AVIF|HEIC|WEBP'
php --ri imagick | sed -n '1,160p'
php -r '$i=new Imagick(); var_dump($i->queryFormats("AVIF")); var_dump($i->queryFormats("WEBP"));'

Step 1 — Install build prerequisites and delegates (AVIF + WebP)

AVIF support is normally provided through libheif (HEIF/AVIF), and WebP through libwebp. Install the dev packages before building ImageMagick so the configure script can detect them.

sudo apt update

# Toolchain and build helpers
sudo apt install -y build-essential pkg-config git wget ca-certificates

# Delegates for AVIF/HEIC and WebP
sudo apt install -y libheif-dev libwebp-dev

Important nuance: AVIF encoding depends on how libheif was built and which AV1 codec backends it has available (e.g., libaom, rav1e, SVT-AV1). The upstream libheif project explains the codec-backend situation here: https://github.com/strukturag/libheif. If your server has libheif but no AV1 encoder backend, ImageMagick may show AVIF read support but disable AVIF encoding.

Step 2 — Build ImageMagick 7 from the official source (recommended for all Ubuntu LTS)

Use the official ImageMagick source installation guide: https://imagemagick.org/script/install-source.php, and download from: https://imagemagick.org/script/download.php.

cd /usr/local/src
sudo mkdir -p imagemagick-src
sudo chown "$USER:$USER" imagemagick-src
cd imagemagick-src

wget https://imagemagick.org/download/ImageMagick.tar.gz
tar -xzf ImageMagick.tar.gz
cd ImageMagick-*

# Enable AVIF/HEIC via libheif and enable WebP via libwebp
./configure --with-heic=yes --with-webp=yes

make -j"$(nproc)"
sudo make install
sudo ldconfig

Why these flags matter:

--with-heic=yes is the practical switch that enables HEIF/AVIF via libheif.
--with-webp=yes enables WebP if libwebp is present.

Step 3 — Verify AVIF + WebP are writable in ImageMagick

magick -list format | egrep 'AVIF|HEIC|WEBP'

You want AVIF/HEIC and WEBP to show up as writable (commonly indicated by rw+ style flags depending on how you view formats).

If AVIF is missing entirely

That almost always means the build didn’t pick up libheif. Re-check that libheif-dev was installed before ./configure, then rebuild.

If AVIF exists but isn’t writable

That commonly means libheif is present but can’t encode AV1 due to missing codec backends. In this scenario, it’s not a PHP problem; it’s a libheif/codec backend problem. An example of this being discussed in ImageMagick issue tracking is here: https://github.com/ImageMagick/ImageMagick/issues/4380.

Step 4 — Install PHP 8.3 (Ubuntu differences)

Ubuntu 24.04 (Noble)

Ubuntu 24.04 is the simplest because PHP 8.3 packages are available by default:

sudo apt install -y php8.3 php8.3-cli php8.3-fpm php8.3-dev php-pear

Ubuntu 22.04 (Jammy) and Ubuntu 20.04 (Focal)

These releases often require an additional repository to get PHP 8.3. A commonly referenced guide that walks through this process is: https://php.watch/articles/php-8.3-install-upgrade-on-debian-ubuntu.

Once PHP 8.3 is available:

sudo apt install -y php8.3 php8.3-cli php8.3-fpm php8.3-dev php-pear

Step 5 — Install Imagick for PHP 8.3 (pin a known-good version)

Install the header package used by the extension build:

sudo apt install -y libmagickwand-dev

Pin Imagick to a PHP 8.3-safe release

There is a real PECL install failure on PHP 8.3 caused by stub/preprocessor issues documented in Imagick issue #640: https://github.com/Imagick/imagick/issues/640.

Install a release that includes the fix (for example Imagick 3.8.0 from PECL): https://pecl.php.net/package/imagick/3.8.0.

sudo pecl install imagick-3.8.0

Enable it:

echo "extension=imagick.so" | sudo tee /etc/php/8.3/mods-available/imagick.ini
sudo phpenmod imagick
sudo systemctl restart php8.3-fpm

Verify linkage and format availability:

php --ri imagick | sed -n '1,160p'
php -r '$i=new Imagick(); var_dump($i->queryFormats("AVIF")); var_dump($i->queryFormats("WEBP"));'

Troubleshooting: high-signal gotchas and exact fixes

Gotcha 1 — `magick` shows AVIF, but PHP Imagick doesn’t

Symptom: magick -list format includes AVIF/HEIC, but Imagick::queryFormats("AVIF") is empty.

Cause: Imagick linked against a different ImageMagick build than your shell is using (common when IM7 is in /usr/local but PHP linked against IM6 in /usr/lib).

Fix: Rebuild Imagick with pkg-config pointing to IM7 and reinstall:

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/local/lib64/pkgconfig:$PKG_CONFIG_PATH
sudo pecl uninstall imagick
sudo pecl install imagick-3.8.0
sudo systemctl restart php8.3-fpm
php --ri imagick | sed -n '1,120p'

Gotcha 2 — Ubuntu 22.04 transparent PNG → AVIF becomes black

Symptom: Transparent PNGs become black in AVIF output.

Cause: Known issue on Jammy’s IM6 baseline, tracked as https://bugs.launchpad.net/bugs/1980124, with follow-on confirmation and patch discussion at https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1040307.

Fix: Use the ImageMagick 7 build path in this guide (or ensure your deployed ImageMagick includes the fixes referenced in the bug threads).

Gotcha 3 — PECL Imagick fails on PHP 8.3 during install

Symptom: pecl install imagick fails with stub/preprocessor errors like “Unterminated preprocessor conditions”.

Cause: Documented in https://github.com/Imagick/imagick/issues/640.

Fix: Pin to a fixed release like https://pecl.php.net/package/imagick/3.8.0.

Gotcha 4 — AVIF is present but not writable

Symptom: AVIF appears in magick -list format but encoding fails or AVIF is read-only.

Cause: libheif present without an AV1 encoder backend (see upstream libheif backend discussion: https://github.com/strukturag/libheif), and ImageMagick may disable AVIF encoding in that case (see discussion patterns like https://github.com/ImageMagick/ImageMagick/issues/4380).

Fix: Ensure your platform’s libheif build includes an AV1 encoder backend appropriate for your environment policy (distro packaging differs).

Tuning WebP and AVIF in Imagick: parameters that actually matter

Your plugin will be far more consistent if you expose a small, meaningful set of parameters:

A “quality” control (0–100)
An “encoding effort/speed” control
A “chroma mode” control for AVIF when needed

WebP tuning (Imagick)

The authoritative list of WebP defines and defaults is the ImageMagick WebP documentation: https://imagemagick.org/script/webp.php.

Key parameters

setImageCompressionQuality(n) — primary quality knob.
webp:method (0–6) — effort knob; higher often reduces size at the same quality but costs CPU.
webp:alpha-quality (0–100) — improves alpha edges on transparent images.
webp:lossless (0/1) — use for UI assets where artifacts are unacceptable.

Recommended presets

Balanced (good default for photos)

quality: 82
webp:method: 6
webp:alpha-quality: 95

$im = new Imagick($src);
$im->setImageFormat('webp');
$im->setImageCompressionQuality(82);
$im->setOption('webp:method', '6');
$im->setOption('webp:alpha-quality', '95');
$im->writeImage($dest);

Fast regeneration (large libraries/thumbnails)

quality: 75
webp:method: 4

$im = new Imagick($src);
$im->setImageFormat('webp');
$im->setImageCompressionQuality(75);
$im->setOption('webp:method', '4');
$im->writeImage($dest);

AVIF tuning (Imagick)

ImageMagick exposes AVIF-related controls through HEIC/HEIF defines documented in the ImageMagick defines reference: https://imagemagick.org/script/defines.php.

Key parameters

setImageCompressionQuality(n) — primary quality knob for AVIF output in this pipeline.
heic:speed — controls encode effort vs CPU time.
heic:chroma — chroma subsampling mode (420, 422, 444), with 420 typically being the best size/quality balance for photographs.

Recommended presets

Balanced (best default for photos)

quality: 55
heic:speed: 7
heic:chroma: 420

$im = new Imagick($src);
$im->setImageFormat('avif');
$im->setImageCompressionQuality(55);
$im->setOption('heic:speed', '7');
$im->setOption('heic:chroma', '420');
$im->writeImage($dest);

Fast regeneration (large libraries)

quality: 48
heic:speed: 9
heic:chroma: 420

$im = new Imagick($src);
$im->setImageFormat('avif');
$im->setImageCompressionQuality(48);
$im->setOption('heic:speed', '9');
$im->setOption('heic:chroma', '420');
$im->writeImage($dest);

UI assets / sharp edges

quality: 70
heic:speed: 6
heic:chroma: 444 (only if you observe chroma bleeding)

$im = new Imagick($src);
$im->setImageFormat('avif');
$im->setImageCompressionQuality(70);
$im->setOption('heic:speed', '6');
$im->setOption('heic:chroma', '444');
$im->writeImage($dest);

A minimal server self-test you can include in support docs

When a user reports “AVIF doesn’t work”, ask them for the output of:

magick -version
magick -list format | egrep 'AVIF|HEIC|WEBP'
php --ri imagick | sed -n '1,160p'

Those three snippets usually identify the root cause immediately: missing delegates, AVIF read-only, or PHP linking against the wrong ImageMagick build.

Installing ImageMagick + Imagick for PHP 8.3 on Ubuntu (20.04 / 22.04 / 24.04) with Reliable AVIF + WebP Output

What Ubuntu ships by default (and why you shouldn’t blindly trust it for AVIF)

Target outcome

Step 1 — Install build prerequisites and delegates (AVIF + WebP)

Step 2 — Build ImageMagick 7 from the official source (recommended for all Ubuntu LTS)

Step 3 — Verify AVIF + WebP are writable in ImageMagick

If AVIF is missing entirely

If AVIF exists but isn’t writable

Step 4 — Install PHP 8.3 (Ubuntu differences)

Ubuntu 24.04 (Noble)

Ubuntu 22.04 (Jammy) and Ubuntu 20.04 (Focal)

Step 5 — Install Imagick for PHP 8.3 (pin a known-good version)

Pin Imagick to a PHP 8.3-safe release

Troubleshooting: high-signal gotchas and exact fixes

Gotcha 1 — magick shows AVIF, but PHP Imagick doesn’t

Gotcha 2 — Ubuntu 22.04 transparent PNG → AVIF becomes black

Gotcha 3 — PECL Imagick fails on PHP 8.3 during install

Gotcha 4 — AVIF is present but not writable

Tuning WebP and AVIF in Imagick: parameters that actually matter

WebP tuning (Imagick)

Key parameters

Recommended presets

AVIF tuning (Imagick)

Key parameters

Recommended presets

A minimal server self-test you can include in support docs

Gotcha 1 — `magick` shows AVIF, but PHP Imagick doesn’t