PIE: PHP Foundation's Official Extension Installer Replaces PECL

What Are PHP Extensions?

PHP extensions are C-language modules that add functionality to PHP. Some ship with PHP (e.g., intl, gd, pdo_mysql), while others like redis, imagick, and xdebug require separate installation. Until now, the primary tool for these was PECL.

What Is PIE?

PIE (PHP Installer for Extensions) is the PHP Foundation's official PHP extension installer. Distributed as a PHAR file like Composer, it uses Packagist to locate packages. Unlike Composer, which brings PHP libraries into a project, PIE compiles and installs extensions directly into the PHP installation itself.

In 2025, the PHP community voted 36–0 on an RFC to recommend PIE and deprecate PECL. As of this writing, PIE's latest version is 1.5.3 , released October 21, 2026. PECL remains usable but is no longer officially recommended; future RFCs will decide its removal.

Old Installation Methods

PECL

PECL (PHP Extension Community Library) installs extensions via pecl install redis. Drawbacks:

Interactive prompts for build options (e.g., igbinary, lzf, zstd, msgpack, lz4, system liblz4), requiring manual responses even for defaults.

Manual enablement : after installation, you must edit php.ini to add extension=redis.so or use docker-php-ext-enable in Docker.

Separate repository : packages live on pecl.php.net with hand-written package.xml per version.

No project-level definition : cannot declare required extensions for a project or install them all at once.

docker-php-ext-install

Official PHP Docker images provide docker-php-ext-install for bundled extensions (e.g., intl, pdo_mysql). External extensions like Redis still need PECL:

RUN docker-php-ext-install intl pdo_mysql \
  && pecl install redis \
  && docker-php-ext-enable redis

OS Packages

Debian/Ubuntu can install extensions from repositories like Ondřej Surý's (deb.sury.org), but only for PHP versions built by that source and limited to packaged versions.

Manual Compilation

Download source and run phpize, ./configure, make, make install, then edit php.ini.

Installing PIE

Requires PHP 8.1+ (PIE itself can install extensions for other PHP versions). On Linux/macOS:

curl -fL --output /tmp/pie.phar \
  https://github.com/php/pie/releases/latest/download/pie.phar \
  && gh attestation verify --owner php /tmp/pie.phar \
  && sudo mv /tmp/pie.phar /usr/local/bin/pie \
  && sudo chmod +x /usr/local/bin/pie

The gh attestation verify step uses GitHub CLI to confirm the file was published by the PHP team.

Using PIE

Extensions are installed by Packagist name: pie install phpredis/phpredis Example output on a clean Docker image with PHP 8.5:

🥧 PHP Installer for Extensions (PIE) 1.5.3, from The PHP Foundation
You are running PHP 8.5.12
Target PHP installation: 8.5.12 nts, on Linux/OSX/etc x86_64 (from /usr/local/bin/php)
Found package: phpredis/phpredis:6.3.0 which provides ext-redis
phpize complete.
Configure complete with options: --with-php-config=/usr/local/bin/php-config
Build complete: .../phpredis/phpredis/modules/redis.so
Install complete: /usr/local/lib/php/extensions/no-debug-non-zts-20250925/redis.so
✅ Extension phpredis/phpredis:6.3.0 is enabled and loaded in /usr/local/bin/php

Note the last line: PIE not only compiles and installs but automatically enables the extension , eliminating the need to hunt for php.ini.

Search for packages: pie search xdebug Other useful commands: pie info vendor/package – show extension info and compilable options. pie show – list extensions installed via PIE. pie upgrade – update all PIE-installed extensions to versions matching their constraints. pie download / pie build – download or download and compile without installing. pie check-build-tools – verify presence of gcc, make, autoconf, etc.

Version Constraints Like Composer

Use Composer-style version constraints: pie install xdebug/xdebug:^3.4 Build options that PECL asked interactively are passed as arguments. List available options with pie info.

Killer Feature: Project-Wide Extensions

Composer already knows required extensions via composer.json 's ext-* section:

{
  "name": "jumpbg/blog-demo",
  "require": {
    "php": "^8.4",
    "ext-redis": "^6.0",
    "ext-intl": "*"
  }
}

Running pie install inside the project folder (no arguments) checks missing extensions and offers to install them. In CI/Docker, use --select to pre-choose packages: pie install --select redis=phpredis/phpredis Test output:

Checking extensions for your project jumpbg/blog-demo (path: /app)
requires: ext-intl:* 🚫 Missing
PIE could not find any potential matches for ext-intl; if you know which package to use, specify --select extension=vendor/package in the `pie install` options.
requires: ext-redis:^6.0 🚫 Missing
Found package: phpredis/phpredis:6.3.0 which provides ext-redis
...
✅ Extension phpredis/phpredis:6.3.0 is enabled and loaded in /usr/local/bin/php
Finished checking extensions.

PIE installed Redis but could not find a package for intl (bundled extensions still use docker-php-ext-install in official Docker images).

With pie.json and pie.lock, PIE can install exact locked versions via pie install --from-lock.

PIE in Docker

PIE publishes a minimal Docker image containing only the PHAR. Mount it at build time so it doesn't appear in the final image:

FROM php:8.5-cli
RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin/pie \
    apt-get update \
    && apt-get install -y --no-install-recommends unzip \
    && pie install phpredis/phpredis \
    && rm -rf /var/lib/apt/lists/*

PIE needs unzip (or the Zip extension) to extract sources, just like Composer.

PIE on Windows

On Windows, extensions are distributed as pre-compiled DLLs. PIE downloads the DLL matching your PHP version and places it in the extension directory — no compilation tools required.

PECL vs. PIE Comparison

Repository : PECL uses pecl.php.net; PIE uses Packagist.

Package definition : PECL uses package.xml; PIE uses composer.json.

New version release : PECL requires manual entry in package.xml; PIE uses Git tags, like Composer packages.

Versions : PECL supports specific or stable versions only; PIE supports Composer constraints (e.g., ^3.4).

Enable in php.ini : PECL usually manual; PIE automatic.

Project extensions : PECL has none; PIE reads composer.json via pie install.

Full upgrade command : PECL uses pecl upgrade-all; PIE uses pie upgrade.

Windows : PECL requires manual DLL download; PIE automatically downloads ready-made DLLs.

Status : PECL is deprecated; PIE is officially recommended.

Command equivalents: pecl install xdebug →

pie install xdebug/xdebug

pecl info xdebug

→

pie info xdebug/xdebug

pecl list

→

pie show

pecl search

→

pie search

pecl download xdebug

→

pie download xdebug/xdebug

pecl build xdebug

→

pie build xdebug/xdebug

pecl upgrade-all

→

pie upgrade

Which Extensions Support PIE?

Many popular extensions already support PIE, including:

xdebug/xdebug

phpredis/phpredis

apcu/apcu

imagick/imagick

mongodb/mongodb-extension

php-memcached/php-memcached

swoole/swoole

pecl/pcov

open-telemetry/ext-opentelemetry

Full list at packagist.org/extensions.

Extension maintainers can add PIE support by publishing a composer.json with type php-ext (or php-ext-zend for Zend extensions) and tagging releases on Git.

Conclusion

PIE does for PHP extensions what Composer did for PHP libraries: a familiar way to find, install, and update extensions with version info, automatic enabling, and no manual php.ini edits. It can install all missing project extensions in one command — ideal for local development, CI, and Docker. PECL still works, but for new projects or Dockerfile updates, switch to PIE now .