can't install intl in php:7.4-alpine

can't install intl in php:7.4-alpine

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

Stefan Bogdanescu

Founder & Senior Architect

Can't Install intl in PHP:7.4-Alpine? The Missing Piece

You are encountering a classic Docker build-time versus runtime inconsistency. Your Dockerfile explicitly runs docker-php-ext-install intl, and when you inspect the container shell, php -m confirms the extension is loaded. However, your application throws a fatal error stating the Locale class is missing. This discrepancy indicates that while the C extension itself might be compiled, the PHP runtime environment inside the Apache handler cannot see it, or the build process failed silently in a way that isn't obvious until the application starts.

The root cause lies in how Alpine Linux handles dependencies compared to Debian-based images. The php:7.4-alpine image uses a minimal set of tools and headers. To compile extensions like intl, you need specific development libraries, most notably the ICU (International Components for Unicode) headers. Your Dockerfile attempts to install these via apk add ... icu-dev. However, simply adding icu-dev is often insufficient for the intl extension in Alpine environments if the build scripts cannot locate the necessary header files or if the phpize configuration step fails due to missing dependencies like libicu-dev.

In your current setup, you are using multiple RUN instructions. While this keeps the image layers smaller and builds faster, it can sometimes obscure where a dependency resolution failed. If docker-php-ext-install intl runs but silently fails because icudev isn't correctly linked or if libicu-dev is missing specific sub-packages, the extension might not be fully integrated into the Apache SAPI.

The most reliable fix for this specific error in PHP 7.4 Alpine is to ensure that all required development headers are present before attempting to compile the extension. Instead of relying solely on the standard apk add without verifying the presence of the full ICU development package, you should explicitly install libicu-dev. Furthermore, sometimes the order of operations matters; ensuring zlib-dev, libpng-dev, and icu-dev are installed before running docker-php-ext-install is critical.

Here is a corrected approach for your Dockerfile:

FROM php:7.4-alpine

ENV APACHE_DOCUMENT_ROOT /var/www/app/public

# Install Apache and Composer first
RUN apk add --no-cache \
    apache2 \
    apr-util-dev \
    curl-dev \
    file-dev \
    gcc \
    g++ \
    libtool \
    linux-headers \
    make \
    musl-dev \
    openssl-dev \
    pcre-dev \
    pkgconfig \
    tar

# Install PHP dependencies and development headers
RUN apk add --no-cache \
    icu-dev \
    libpng-dev \
    zlib-dev \
    freetype-dev \
    tiff-dev \
    jpeg-dev \
    libxml2-dev

# Copy application source
COPY ./src /var/www/app

# Compile and enable extensions. Note the explicit configuration step.
RUN docker-php-ext-configure intl \
    && docker-php-ext-install \
        bcmath \
        mbstring \
        pdo_mysql \
        mysqli \
        gd \
        intl \
        opcache

# Configure Apache to use PHP as a module
RUN echo "LoadModule php7_module /usr/lib/apache2/modules/libphp.so" >> /etc/apache2/httpd.conf
RUN echo "AddHandler application/x-httpd-php .php" >> /etc/apache2/httpd.conf
RUN echo "DirectoryIndex index.php index.html" >> /etc/apache2/httpd.conf

# Set permissions and run composer
RUN chmod -R 775 /var/www/app \
    && chown -R www-data:www-data /var/www/app \
    && cd /var/www/app && composer install --no-dev --optimize-autoloader

COPY ./apache /etc/apache2

CMD ["/usr/sbin/httpd", "-DFOREGROUND"]

The critical addition here is the explicit docker-php-ext-configure intl command. In some versions of the Alpine image, simply running docker-php-ext-install without configuring first can lead to incomplete builds if the internal cache doesn't pick up the latest ICU headers. By forcing a configuration step, you ensure that phpize correctly detects the icudev headers before compiling the extension code.

Additionally, note the inclusion of apru-util-dev. The standard apache2 module in Alpine often requires APR utilities to function correctly with PHP modules. Without this, Apache might fail to load the PHP handler entirely, resulting in a 500 error that masks the specific missing extension issue.

If you continue to face issues, consider switching from docker-php-ext-install to a dedicated installer script like mlocati/docker-php-extension-installer. While you mentioned having trouble with iconv previously, that tool handles dependency resolution more robustly across different base images. It automatically pulls the necessary headers and compiles extensions in one go, reducing the chance of human error in managing apk dependencies.

For production environments, always verify the extension inside the running container using php -m before deploying. If intl appears in the list but your app still fails, check your Apache error log specifically for messages regarding "module not found" or "shared object file cannot be loaded," which point to Apache configuration issues rather than PHP compilation errors.

Our network