How to enable pdo_mysql in the php docker image

How to enable pdo_mysql in the php docker image

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

Stefan Bogdanescu

Founder & Senior Architect

How to Enable PDO MySQL in the PHP Docker Image

When building a PHP application inside a container, it is common to assume that enabling an extension via docker-php-ext-install makes it immediately available at runtime. In your specific scenario using php:7.1-apache, you are encountering a classic mismatch between how extensions are compiled into the base image and how they are loaded by the web server process.

The command RUN apt-get update && docker-php-ext-install pdo_mysql executes successfully during the build phase. This means the PHP CLI binary, which is used to run commands like php -m or generate a phpinfo() page from the terminal, now has the pdo_mysql extension loaded. However, the Apache web server process running inside that same container likely does not see this change because it relies on its own compiled module list at startup time.

The core issue lies in the fact that the php:7.1-apache base image ships with a default set of extensions enabled for Apache via .ini files and shared object loading, but custom-installed extensions often require explicit reloading or configuration updates to be picked up by the web server process without restarting the container service logic correctly. More critically in many versions of the PHP Docker images, simply installing an extension does not automatically append its configuration block (like extension=pdo_mysql) to the Apache-specific configuration file (/etc/apache2/mods-available/pdo_mysql.load might exist, but the .ini file path needs to be active).

To resolve this without rebuilding with complex custom compile flags, you must ensure the extension is explicitly loaded in the Apache configuration. The standard approach for PHP 7.1 images involves adding a line to the php.ini or creating a dedicated configuration drop-in directory that Apache reads.

You can achieve this by modifying your Dockerfile to create a custom conf.d directory and drop the extension file there, then restarting the service logic within the container context. Here is an updated approach:

FROM php:7.1-apache
RUN apt-get update && apt-get install -y \
    build-essential \
    libzip-dev \
    unzip \
    git \
    && pecl install pdo_mysql \
    && docker-php-ext-enable pdo_mysql
COPY . /var/www/html
# Ensure the extension is loaded for Apache specifically if not defaulting automatically
RUN mkdir -p /usr/local/etc/php/conf.d/ && echo "extension=pdo_mysql.so" > /usr/local/etc/php/conf.d/pdo_mysql.ini
EXPOSE 80

Wait, there is a nuance here. The docker-php-ext-install command usually handles enabling the extension for the CLI, but for Apache, you often need to ensure the .so file is copied or symlinked into the correct location and that Apache is configured to load it. In PHP 7.1 images, the docker-php-ext-install pdo_mysql command typically installs the extension and enables it for the CLI by default. However, the Apache server might not reload this specific module automatically depending on the image version's internal defaults.

A more robust method that works consistently across older PHP versions like 7.1 is to explicitly tell Apache where to find the new extension or ensure the extension directive is present in the file Apache reads. The most reliable fix is often adding the configuration line directly:

FROM php:7.1-apache
RUN apt-get update && docker-php-ext-install pdo_mysql
COPY . /var/www/html
# Explicitly enable the extension for the web server process if it wasn't picked up automatically
RUN echo "extension=pdo_mysql.so" >> /usr/local/etc/php/conf.d/docker-php-ext-pdo.ini
EXPOSE 80

However, looking at the php:7.1-apache documentation and behavior, the docker-php-ext-install pdo_mysql command should ideally handle both CLI and Apache if the image is up to date for that version. If it fails, it suggests a permission issue or a missing library dependency during the RUN phase that wasn't caught in the build logs.

Another frequent pitfall involves the volume mount in your docker-compose.yml. You are mounting .:/var/www. In the original Dockerfile, you copied to /var/www, but then the compose file overwrites the contents of /var/www with your local project code. If your project does not contain a specific configuration for PHP-FPM or Apache that includes the PDO extension in its php.ini, and if the base image's default php.ini excludes it, you need to ensure the extension is loaded before Apache starts serving requests.

Consider adjusting your Dockerfile to place the configuration after the copy command or ensuring the docker-php-ext-enable command creates a symlink that survives the volume mount logic (though usually, system config files in /etc or /usr/local/etc are preserved while /var/www is replaced).

FROM php:7.1-apache
RUN apt-get update && apt-get install -y zip unzip git
RUN docker-php-ext-install pdo_mysql pdo_pgsql mysqli
# Ensure the extension is active for Apache by adding to conf.d
RUN echo "extension=pdo_mysql.so" >> /usr/local/etc/php/conf.d/docker-php-ext-pdo.ini
COPY --chown=www-data:www-data . /var/www/html
EXPOSE 80

By appending the extension configuration to /usr/local/etc/php/conf.d/, you ensure that Apache reads it regardless of whether the base image's default list included it. This is a safer bet when dealing with legacy PHP versions where automatic detection was less reliable.

Finally, verify your MySQL service connectivity. Even if PDO is enabled, connection strings in your application need to match the credentials defined in your docker-compose.yml. The depends_on directive ensures the container starts after MySQL, but remember that depends_on does not wait for MySQL to be ready to accept connections; you might need a health check script or a delay if your PHP app fails immediately upon startup.

If you are migrating from legacy setups to modern stacks, consider upgrading to PHP 8.x where the Docker images handle extension enabling more predictably between CLI and FPM/Apache modes. For now, the explicit configuration file addition is the definitive fix for the php:7.1-apache image.

Our network