Installing GD in Docker

Installing GD in Docker

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

Stefan Bogdanescu

Founder & Senior Architect

Resolving the Missing png.h Header When Building PHP-GD in Docker

Encountering a configure: error: png.h not found message while attempting to install the GD extension inside a container is a classic symptom of a broken dependency chain, not a mystery about the PHP interpreter itself. The Dockerfile provided attempts to build an image based on php:5.6-apache, but it treats the container as if it were building from a pristine base or has failed to account for what packages are actually included in that specific upstream image.

When you run apt-get install -y zlib1g-dev, you might assume this satisfies all development requirements. While zlib is essential for compression support, it does not automatically pull in the libpng development headers required by GD. The GD extension depends on a suite of image manipulation libraries—FreeImage, FreeType, and most critically, libpng (Portable Network Graphics) and libjpeg. If these specific development packages are missing from your apt-get list, the PHP build process cannot locate the necessary .h header files during compilation, resulting in the immediate failure you observed.

To fix this, you must explicitly install the missing dependencies before attempting to compile the extension. The command needs to be updated to include libpng-dev and libjpeg-dev. Since GD often relies on FreeType for font rendering and FreeImage for image format support, including those headers is also best practice unless you are strictly limiting GD functionality.

Here is the corrected sequence of operations:

RUN apt-get update && \
    apt-get install -y \
        libpng-dev \
        libjpeg-dev \
        libfreetype6-dev \
        libmcrypt-dev \
        libxml2-dev \
        zip \
        unzip && \
    docker-php-ext-install gd

Note that libxml2-dev and zip/unzip are frequently required in production PHP environments, so installing them alongside GD prevents future dependency issues. The command docker-php-ext-install automatically fetches the necessary PECL metadata and handles the compilation logic, but it relies entirely on the host OS (inside the container) having the correct C headers available in /usr/include.

There is a significant trade-off to consider regarding the base image choice: php:5.6-apache. PHP 5.6 reached end-of-life in December 2018 and received security updates until January 2021. Continuing to maintain a system based on this version introduces substantial security risks, as modern PHP versions no longer bundle the same legacy libraries by default, and many upstream packages have dropped support for compiling against such old C standards. If you are maintaining an existing system where upgrading the entire stack is not immediately feasible, you are restricted to patching the Dockerfile as shown above, but you should plan a migration path away from PHP 5.6 due to the lack of long-term security patches.

Another potential pitfall in the original Dockerfile is the sequential execution of apt-get update. The first run installs sendmail, and the second updates packages before installing zlib1g-dev. While this works, it is inefficient. Combining these steps into a single RUN instruction leverages Docker's layer caching effectively and reduces the number of transient layers written to the image filesystem.

If you are working within a Laravel ecosystem or maintaining a web stack that relies heavily on image processing features like avatar generation or thumbnail creation, ensuring the GD extension is correctly compiled with all necessary headers is critical. For teams managing legacy stacks where upgrading PHP versions is blocked by third-party dependencies, verifying that libpng-dev and its companions are present in the container build context becomes a mandatory checklist item before every docker build.

For more modern projects requiring complex image processing or those looking to move away from the deprecated 5.6 branch, exploring resources at https://laravelcompany.com might offer insights into contemporary PHP architectures and how to handle image processing requirements with newer, supported versions of the language where GD is often pre-installed with full dependencies.

Our network