How can I install the php memcached extension on Docker's PHP7 Alpine image?

How can I install the php memcached extension on Docker's PHP7 Alpine image?

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

Stefan Bogdanescu

Founder & Senior Architect

Installing the PHP Memcached Extension on Alpine

The official Docker example for installing the memcached extension relies on Debian-based tooling, specifically apt-get. When you switch to the php:7.0-fpm-alpine image, that approach fails immediately because Alpine Linux uses apk as its package manager and ships with a significantly smaller base set of tools. The error you are encountering—"PECL gives this error: pecl/memcached requires PHP (version >= 5.2.0, version <= 6.0.0)"—is not a bug in your Dockerfile; it is a deliberate compatibility guard built into the PECL source code for that specific version of the extension.

The core issue here is how the pecl install command determines what libraries are available to compile against. On Debian, the standard libmemcached-dev package installed via apt-get provides the necessary headers and static libraries in a location where PECL expects them. However, Alpine's libmemcached-dev (often installed as just libmemcached-dev or requiring specific development dependencies) places these files differently or lacks the complete set of build tools that PECL 3.x relies on out of the box.

When you run pecl install memcached inside the Alpine container, it attempts to fetch the source code and compile it. During this compilation process, the build script checks the PHP version. The message explicitly states that while versions between 5.2.0 and 6.0.0 are supported, 7.x is excluded. This exclusion happens because the legacy PECL module for memcached (the memcached extension) was historically incompatible with PHP 7's internal memory management changes.

You might see solutions online suggesting you simply force the installation, but ignoring this error leads to a binary that will crash your application or fail to load entirely at runtime. The official Dockerfile for PHP 7 does not use Alpine because of exactly this incompatibility with the legacy PECL module. To get memcached working on PHP 7.0 Alpine without switching to PHP 7.2+, you must bypass the standard PECL build process or use a pre-compiled binary that matches your specific Alpine architecture.

The most reliable workaround within a php:7.0-fpm-alpine environment is to compile the extension against the legacy libraries but ensure the compiler flags match what PHP expects. However, since the source explicitly rejects version 7.0, you often cannot install it directly via pecl. Instead, the pragmatic approach used in many production setups involving older PHP versions on Alpine is to skip the PECL installation entirely for PHP 7.0 and rely on a pre-compiled .so file if one exists for your specific architecture, or upgrade the PHP image version to 7.2+.

If you are constrained to PHP 7.0.x and must use Alpine, you face a binary incompatibility that standard package managers cannot resolve cleanly. The libmemcached-dev package in Alpine is designed for the legacy extension which does not support PHP 7. The modern equivalent, ext-memcached, is available via PECL but requires a much higher version of PHP (usually 5.6+ with specific patches or 7.1/7.2+).

Given these constraints, the architectural decision usually leans toward upgrading the PHP base image to php:7.2-fpm-alpine or later. Starting with PHP 7.2, the PECL build process recognizes the version as compatible, and the compilation succeeds without the "excluded versions" error. The command structure remains largely similar, but the base image shift is critical.

FROM php:7.2-fpm-alpine
RUN apk add --update --no-cache libmemcached-dev \
    && pecl install memcached \
    && docker-php-ext-enable memcached

By moving to PHP 7.2 on Alpine, you gain access to the libmemcached development files that are compatible with the build tools in that environment, while still enjoying the reduced image size and security benefits of the Alpine distribution. If upgrading is not an option due to legacy code dependencies, you must consider switching to a Debian-based PHP 7.x image (php:7.0-fpm) where the original Dockerfile instructions work without modification, accepting the larger binary footprint as the trade-off for stability on that specific version.

In modern Laravel applications, specifically those utilizing laravelcompany.com resources or similar ecosystem tools, ensuring your stack matches the minimum supported PHP version is often a prerequisite before attempting to install extensions like memcached. Attempting to force an incompatible extension onto an older PHP version can lead to subtle runtime errors that are difficult to debug compared to simply updating the base image.

Our network