Docker + PHP:8.1.1-FPM how to install imagick php extension?

Docker + PHP:8.1.1-FPM how to install imagick php extension?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Resolving Docker + PHP 8.1.1 FPM ImageMagick Extension Issues

When building a PHP application inside a Docker container, specifically using the php:8.1.1-fpm base image, adding external dependencies like ImageMagick often hits a wall during the Composer install phase. The error message is explicit: ext-imagick ^3.6 but it is missing from your system. This happens because the official PHP Docker images are opinionated about their extension set to minimize footprint and maximize stability. They do not include imagick by default, nor do they always provide a straightforward package manager entry point for it.

The immediate reaction many developers have is to try installing the extension via apt-get. Commands like apt install php-imagick or apt install php8.1-imagick will fail with errors stating the package is not available or only found in another source. This is because the Debian/Ubuntu repositories do not maintain a single binary package named php-imagick compatible with the specific PHP version inside the slim Docker image. The architecture and linking required for PECL extensions are distinct from standard library packages.

Attempting to use docker-php-ext-install imagick directly also fails if the underlying libraries are missing or configured incorrectly. The command relies on a pre-installed header file (.h) that matches the compiled PHP version. If these headers are not present in /usr/include/php/..., the PECL installer cannot find the necessary definitions to compile the C extension against your PHP binary.

The solution lies in explicitly installing the development libraries required to build the imagick extension from source within the Dockerfile, rather than relying on a pre-compiled binary package. You must install the ImageMagick libraries and their headers before attempting to install the PECL module.

In your Dockerfile, you need to ensure that both the runtime library (imagemagick) and the development kit (libmagickwand-dev) are installed. The libmagickwand-dev package contains the header files necessary for the compiler to generate the shared object file (.so) that PHP will load.

Here is how you should adjust your build sequence:

  1. Install Development Dependencies: Ensure libmagickwand-dev and imagemagick are installed using apt-get before any PECL commands. In your provided Dockerfile, this step is already present near the bottom (RUN apt-get install -y libmagickwand-dev && RUN apt-get install -y imagemagick). This part is correct.

  2. Install the PECL Extension: Once the headers are available, you can proceed with pecl install imagick. It is crucial to run this after the development libraries are installed but before you copy your application code or lock files, or ensure the environment variables point to the correct PHP installation if multiple versions exist.

  3. Enable the Extension: After compilation succeeds, you must explicitly enable the extension using docker-php-ext-enable imagick. Without this command, the extension remains compiled but inactive. You can verify its presence by running php -m inside the container or checking if the file exists in /usr/local/etc/php/conf.d/docker-php-ext-imagick.ini.

A common pitfall is trying to use composer install immediately after copying files without ensuring the base image has all prerequisites resolved. The order of operations matters. If you install libmagickwand-dev but skip imagick-config, PECL might fail to locate the include paths. However, in modern builds, pecl install imagick usually handles locating its own config if the libraries are present.

If you encounter a specific error like "Could not find image/imagick", it indicates that the headers were not found. Double-check that libmagickwand-dev was installed in the same layer or an earlier layer of your Dockerfile. You can also try specifying the version explicitly if you face compatibility issues, though for PHP 8.1.1, the standard PECL package should work once libmagickwand-dev is present.

Another consideration is the size of the image. Installing ImageMagick and its dev tools increases the base image size significantly. If you are using a multi-stage build, ensure that you only copy these dependencies into the final stage if absolutely necessary, or consider installing them only when needed to keep your production container lean.

Finally, once the extension is installed and enabled via docker-php-ext-enable, run composer install again. The lock file requirement should now be satisfied, and Composer will successfully resolve the ext-imagick dependency without throwing a missing system package error. This approach ensures that your PHP-FPM container has all necessary components to handle image manipulation tasks reliably.

Our network