Docker PHP Extensions: Build-Time vs Runtime Installation

Docker PHP Extensions: Build-Time vs Runtime Installation

When working with PHP in Docker, you have two choices for installing extensions: build them into your Dockerfile (permanent) or install them at runtime via setup scripts (temporary). Build-time installation is the recommended approach.

Build-Time (Dockerfile)

FROM php:8.2-fpm

RUN docker-php-ext-install \
    pdo_pgsql \
    redis \
    gd \
    opcache

Runtime (setup script)

#!/bin/bash
docker exec my-app docker-php-ext-install redis
docker restart my-app

The Problem with Runtime Installation

You must run your setup script after every docker-compose up. If you forget, your application breaks with “extension not found” errors.

Build-time installation ensures extensions are always present when the container starts. No manual intervention required.

Real-World Impact

If your CMS shows “missing database extension” errors after container restarts, check whether the extension is in your Dockerfile’s RUN statement or only installed via post-startup scripts.

Rule of thumb: If it needs to exist every time the container runs, it belongs in your Dockerfile.