PECL Deprecated in PHP: PIE Becomes the New Standard for Extension Installation

PECL Deprecation

In August 2025 the PHP internal community submitted RFC "Recommend PIE and deprecate PECL". The RFC was accepted on 20 September 2025, marking PECL – the extension distribution channel used for over twenty years – as officially deprecated. The PECL website now shows a deprecation banner. While the CLI tools continue to run, the PECL REST metadata interface is being phased out, causing immediate breakage for many Docker image builds.

Docker Build Failure

When executing pecl install, the first step requests extension version and checksum XML from the PECL REST endpoint. With the endpoint shut down the request returns empty, leading to the typical error:

Package "xlswriter" does not have REST info xml available

The empty metadata response causes the verification step to exit with code 1, aborting the installation. This problem is especially acute in Docker container builds where the standard pattern pecl install + docker-php-ext-enable is baked into many Dockerfiles and CI/CD pipelines. For the widely used xlswriter extension, even if the source package xlswriter-1.5.5.tgz is cached locally, the installation still fails because the script still depends on PECL's metadata validation.

PIE – PHP Installer for Extensions

PIE is the official successor to PECL, distributed as a PHAR file with a user experience similar to Composer but focused on system‑level PHP modules and Zend extensions.

Core Features

Strong cross‑version compatibility

PIE itself runs on PHP 8.1 and above.

It can install extensions for any PHP version present on the host, offering broad downward compatibility.

Consistent cross‑platform experience

Linux/macOS : automatically invokes phpize, ./configure, make and requires the usual build toolchain (autoconf, automake, libtool, m4, gcc, php-config or the Debian php-dev package). Since PIE 1.4.0 missing tools are detected and installed automatically.

Windows : distributes pre‑compiled DLL packages, no local build environment needed.

Packagist integration : extensions supported by PIE appear in packagist.org/extensions, removing the need for a separate PECL channel.

Project‑level extension dependency detection : running pie install scans composer.json for ext-* entries, reports missing extensions and guides installation, unifying code and system‑level dependencies.

Automatic extension enablement : after installation PIE attempts to enable the extension by sequentially trying phpenmod (deb.sury.org), docker-php-ext-enable, writing an additional .ini file, or appending to php.ini. The --skip-enable-extension flag disables this behavior.

Migration Strategies

Two practical paths are provided to address the PECL deprecation.

Emergency – Compile from Source (for extensions not yet PIE‑compatible)

If an extension has not been adapted to PIE, download the official source tarball and compile manually, bypassing the PECL REST metadata check. This restores Docker build functionality immediately while still using the official source.

Note : PECL's get endpoint ( pecl.php.net/get/ ) remains operational, but long‑term migration to PIE is recommended.

Example Dockerfile for xlswriter 1.5.5:

FROM php:8.2-fpm

# Install system build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc make autoconf libz-dev pkg-config \
    && rm -rf /var/lib/apt/lists/*

# Download source, compile, and install (bypassing PECL REST)
RUN curl -fsSL https://pecl.php.net/get/xlswriter-1.5.5.tgz -o xlswriter.tgz \
    && mkdir -p /tmp/xlswriter \
    && tar -xf xlswriter.tgz -C /tmp/xlswriter --strip-components=1 \
    && rm xlswriter.tgz \
    && cd /tmp/xlswriter \
    && phpize \
    && ./configure --enable-xlswriter \
    && make -j$(nproc) \
    && make install \
    && rm -rf /tmp/xlswriter

# Enable the extension
RUN docker-php-ext-enable xlswriter

Note : Different extensions have different system dependencies; for xlswriter the zlib library ( libz-dev ) must be installed beforehand.

Long‑Term – Full Migration to PIE

According to the official roadmap, PIE will become the standard tool for PHP extension installation. Projects should gradually replace PECL‑based scripts with PIE commands once extensions are PIE‑compatible and published to the Packagist extension channel.

Prerequisite : the target extension must support PIE and be listed on packagist.org/extensions . For example, xlswriter appears as viest/xlswriter and can be installed directly with PIE.

Installing PIE

Download the pie.phar file (stable or daily build).

Optionally verify the file with GitHub Attestation: gh attestation verify --owner php pie.phar Move it to a directory in PATH and make it executable:

sudo mv pie.phar /usr/local/bin/pie
sudo chmod +x /usr/local/bin/pie

On macOS you can install via Homebrew ( brew install pie); on Fedora/Enterprise Linux 10 (with EPEL) use sudo dnf install pie.

Common PIE Commands

Install a single extension: pie install viest/xlswriter Specify a version constraint (Composer syntax): pie install xdebug/xdebug:^3.4.3 Install for a different PHP binary:

pie install --with-php-config=/usr/bin/php-config7.2 my/extension

Batch install project dependencies (run in project root):

pie install \
    --select example_pie_extension=asgrim/example-pie-extension \
    --select redis=phpredis/phpredis

Docker Integration

The recommended approach is to use the binary‑only PIE image ( ghcr.io/php/pie:bin) and copy the PHAR into the PHP base image:

FROM php:8.2-fpm

# Install build tools and unzip (required by PIE)
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc make autoconf libtool pkg-config libz-dev unzip \
    && rm -rf /var/lib/apt/lists/*

# Copy PIE binary from the official image
COPY --from=ghcr.io/php/pie:bin /pie /usr/local/bin/pie

# Install a PIE‑compatible extension; PIE will automatically call docker-php-ext-enable
RUN pie install --no-cache --auto-install-build-tools viest/xlswriter

Key points:

The ghcr.io/php/pie:bin image provides only the PHAR; the PHP runtime (8.1+) is supplied by the base image.

Tag bin points to the latest stable version; specific versions like 1.5.0-bin are also available.

PIE automatically detects a Docker PHP image and invokes docker-php-ext-enable, removing the need for manual calls.

The --auto-install-build-tools flag installs missing compilation tools in non‑interactive environments.

Multiple extensions can be installed in one command (PIE 1.5+ supports batch installs).

Conclusion

Deprecating PECL is an inevitable evolution of the PHP ecosystem. PIE inherits Composer's engineering advantages, unifies code‑package and extension distribution, and resolves the long‑standing issues of outdated interfaces, insufficient maintenance, and ecosystem fragmentation. Users still relying on pecl install, especially in Docker or CI/CD pipelines, should assess the impact promptly and migrate their build scripts. Extension maintainers must adapt their projects to PIE's publishing standards to ensure continued availability.

Official repository: https://github.com/php/pie