How to Install ImageMagick (php-imagick) for PHP on Ubuntu and Debian

WordPress’ Site Health screen flags imagick as a missing optional module on a freshly built Ubuntu or Debian server. The fix is one APT package on the default repos, plus a couple of small configuration edits if you want PDF thumbnails or a quieter PHP-FPM pool. This DevAnswers guide walks through installing php-imagick on Ubuntu 22.04, 24.04, and 26.04 and Debian 12 and 13, restarting the right SAPI, verifying the module is loaded, and configuring policy and threading.

Prerequisites #

You need a server you control and a working PHP install. If you are still planning the WordPress side, our WordPress install guide for Ubuntu 26.04 covers the full LAMP stack first.

• Ubuntu 22.04, 24.04, or 26.04 LTS, or Debian 12 (Bookworm) or 13 (Trixie)
• sudo access on the server
• PHP already installed (default-repo or Ondřej Surý); confirm with php -v
• A running web server: Nginx with PHP-FPM, or Apache with mod_php / PHP-FPM

Install php-imagick from default repos #

Both Ubuntu and Debian ship a php-imagick metapackage that pulls in the right extension build for the system’s default PHP version. You do not need to know which PHP version you are on; the package manager handles the matching.

The ImageMagick column matters for the PDF support section later: the policy file lives in different directories on IM6 vs IM7 systems. Sources for the version data: packages.ubuntu.com, Debian wiki, and direct package metadata from each distro’s archive.

Run a quick check, refresh the package index, and install:

php -v
sudo apt update
sudo apt install -y php-imagick

You should see something like this on Ubuntu 26.04:

PHP 8.5.0 (cli) (built: ...) ...
...
The following NEW packages will be installed:
  php-imagick php8.5-imagick
Setting up php8.5-imagick (3.8.0-3ubuntu1) ...

Both the imagemagick CLI tools and the underlying libmagickcore libraries come in as transitive dependencies when the package was not already pulled in by another LAMP/LEMP install.

Install on newer PHP via the Sury repository #

If you have moved past your distro’s default PHP version, for example running PHP 8.5 on Ubuntu 24.04 or PHP 8.4 on Debian 12, you are on the Ondřej Surý repository. Surý publishes the imagick build per PHP version (php8.5-imagick, php8.4-imagick, and so on); install the package matching your active PHP. Our PHP upgrade guide covers adding Surý from scratch; the short version is below.

Two reasons people end up here. The first is wanting a newer PHP than the LTS shipped with: Ubuntu 22.04 stops at PHP 8.1 by default, but a modern WordPress install runs comfortably on 8.3 or 8.4. The second is sticking with an older PHP because a plugin or a custom extension has not caught up; Surý keeps multiple PHP versions installable in parallel on the same server.

Ubuntu (Ondřej Surý PPA, signed-by) #

On a minimal install, install curl and gnupg first if they are not already present. Then fetch the PPA signing key from the Ubuntu keyserver, dearmor it into /etc/apt/keyrings/, and write a sources file pointing at the PPA. The signing key fingerprint is B8DC7E53946656EFBCE4C1DD71DAEAAB4AD4CAB6, as published on Launchpad.

sudo apt install -y curl gnupg ca-certificates
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xB8DC7E53946656EFBCE4C1DD71DAEAAB4AD4CAB6" \
  | sudo gpg --dearmor -o /etc/apt/keyrings/ondrej-php.gpg
UBU_CODENAME=$(. /etc/os-release && echo "$VERSION_CODENAME")
echo "deb [signed-by=/etc/apt/keyrings/ondrej-php.gpg] https://ppa.launchpadcontent.net/ondrej/php/ubuntu $UBU_CODENAME main" \
  | sudo tee /etc/apt/sources.list.d/ondrej-php.list
sudo apt update
sudo apt install -y php8.5-imagick

Debian (packages.sury.org, signed-by) #

Surý publishes Debian packages directly from packages.sury.org. Supported releases include Debian 11 (Bullseye), 12 (Bookworm), and 13 (Trixie). The setup follows the same keyring pattern (install curl and gnupg first if a minimal install is missing them):

sudo apt install -y curl gnupg ca-certificates
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://packages.sury.org/php/apt.gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/sury-php.gpg
DEB_CODENAME=$(. /etc/os-release && echo "$VERSION_CODENAME")
echo "deb [signed-by=/etc/apt/keyrings/sury-php.gpg] https://packages.sury.org/php/ $DEB_CODENAME main" \
  | sudo tee /etc/apt/sources.list.d/sury-php.list
sudo apt update
sudo apt install -y php8.4-imagick

Replace php8.4-imagick with whatever PHP version your site is running. The PECL imagick extension supports PHP 8.4 (since release 3.8.0) and PHP 8.5 (latest stable: 3.8.1, released 26 November 2025), per the PECL changelog.

Restart your web server #

APT installs the extension files and runs a maintainer script that enables the module for both the CLI and FPM SAPIs. The new configuration only takes effect after the long-running PHP process restarts. Pick the section that matches your stack:

Nginx with PHP-FPM (or Apache with PHP-FPM) #

Restart the FPM pool. The service name carries the PHP version. To identify which version is installed and running, list the FPM service units:

systemctl list-units --type=service 'php*-fpm.service' --all

Pick the one matching your install (for example php8.5-fpm.service on Ubuntu 26.04, php8.4-fpm.service on Debian 13) and restart it:

sudo systemctl restart php8.5-fpm   # adjust to the version you saw above

Apache with mod_php #

When PHP runs as an Apache module, restarting Apache reloads the extension:

sudo systemctl restart apache2

Verify imagick is loaded #

Confirm the extension is registered against the SAPI you actually use. CLI is the default for terminal commands; your web server uses either FPM or mod_php.

php -m | grep -i imagick
php --ri imagick

Expected output (the first line is from php -m; the rest is from php --ri imagick):

imagick

imagick

imagick module => enabled
imagick module version => 3.8.0
imagick classes => Imagick, ImagickDraw, ImagickPixel, ImagickPixelIterator, ImagickKernel
ImageMagick number of supported formats: 240

Enable PDF support (policy.xml) #

ImageMagick requires Ghostscript to read PDF files. Even with php-imagick loaded, PDF thumbnail generation fails until Ghostscript is installed and the PDF rule in ImageMagick’s security policy is relaxed to allow reads.

sudo apt install -y ghostscript

The policy file path depends on which ImageMagick major version your distro ships. The IM6/IM7 transition is rolling: Ubuntu 22.04, 24.04 and Debian 12 (Bookworm) still ship IM6 (/etc/ImageMagick-6/policy.xml); Ubuntu 26.04 (Resolute) and Debian 13 (Trixie) have moved to IM7 (/etc/ImageMagick-7/policy.xml). The XML inside is structurally identical for the PDF rule, so the edit is the same; only the path differs.

List whichever policy.xml is present:

ls /etc/ImageMagick-{6,7}/policy.xml 2>/dev/null

IM6 and IM7 use opposite default-policy strategies, so the edit you need is different on each. IM6 ships an “allow everything except this specific list” policy, with a per-format deny line you flip to allow. IM7 ships the inverse: a blanket pattern="*" deny followed by a narrow allow list. On IM7, PDF needs an entirely new line rather than an edit.

IM6: edit the existing PDF line #

On Ubuntu 22.04, Ubuntu 24.04, and Debian 12, open the policy file:

sudo nano /etc/ImageMagick-6/policy.xml

Find the existing PDF deny line:

<policy domain="coder" rights="none" pattern="PDF" />

Change rights="none" to rights="read". Read access is enough for WordPress thumbnail generation; the thumbnail itself is written through the PNG/JPG coder, not the PDF coder, so granting write is unnecessary:

<policy domain="coder" rights="read" pattern="PDF" />

IM7: add a new PDF policy line #

On Ubuntu 26.04 and Debian 13, the IM7 default policy denies every coder by default and then narrowly allows a small list. Searching for “PDF” returns no matches because there is no PDF line to edit. The fix is to add one. Open the file:

sudo nano /etc/ImageMagick-7/policy.xml

Just before the closing </policymap> tag, add:

<policy domain="coder" rights="read" pattern="PDF" />

ImageMagick reads policy rules in order and the last match wins, so placing the new rule near the end ensures it overrides the earlier pattern="*" blanket deny. As with IM6, you only need read rights for thumbnail generation.

Save the file (Ctrl+O, Enter, Ctrl+X in nano), then restart your PHP process again so the new policy is picked up. WordPress will now generate previews when a PDF is uploaded to the media library.

Performance tuning (OMP_NUM_THREADS) #

ImageMagick is built with OpenMP and tries to spread one resize across every CPU core by default. Under PHP-FPM, that is the wrong default: each request already runs in its own worker process, and OpenMP’s thread expansion stacks on top, causing contention and over-subscription on busy servers. Pinning OMP_NUM_THREADS to 1 in the FPM pool config gives FPM control over concurrency.

The paths below use PHP 8.5 as an example. Replace 8.5 with whichever version FPM is actually running on your server (use the same systemctl list-units command from the Restart section to confirm):

sudo nano /etc/php/8.5/fpm/pool.d/www.conf

Add this line near the other env[] entries:

env[OMP_NUM_THREADS] = 1

Restart FPM and run a quick smoke test:

sudo systemctl restart php8.5-fpm
sudo php-fpm8.5 -tt 2>&1 | grep OMP_NUM

You should see the variable set in the parsed config:

[05-May-2026 ...] NOTICE: env[OMP_NUM_THREADS] = 1

Troubleshooting #

Restarted Apache but the site uses PHP-FPM #

A common gotcha is restarting apache2 while the live PHP process is FPM. The fix is to restart the right service. Confirm which one is actually serving requests:

ps aux | grep -E "[p]hp-fpm|[a]pache2" | head -5

If you see php-fpm: processes, you need systemctl restart php8.X-fpm; if you only see apache2 children, you are on mod_php and Apache restart was correct.

php -m shows imagick but Site Health does not #

CLI sees the extension because it loads cli/php.ini. WordPress runs under FPM (or mod_php) and uses a different config. Reload the FPM service after install. If that does not fix it, your system PHP and your web PHP are different versions; install the matching extension package (php8.5-imagick, php8.4-imagick, etc.) for the version FPM is running.

PDF thumbnails still fail #

Two checks. First, did Ghostscript actually install? command -v gs should return /usr/bin/gs. Second, did you restart PHP after editing policy.xml? The policy file is read at process start; running edits do not propagate until the pool recycles.

Multiple PHP versions installed at once #

When Surý is in play, the server can have php8.2, php8.4, and php8.5 installed simultaneously, each with its own FPM pool, ini directory, and extension set. Use update-alternatives --display php to see which CLI binary wins the php name; check the FPM unit file (systemctl cat php8.4-fpm) for the exact php-fpm binary the pool runs. Site Health reflects the FPM version, not the CLI version, so the matching phpX.Y-imagick package has to be installed against whichever version FPM is actually running.

Next steps #

With php-imagick loaded against the right SAPI, the WordPress media library can now generate WebP variants and PDF thumbnails on upload. If you are still building out the same VPS, our PHP mail with Postfix guide handles outbound mail in the same APT-driven style.