If your Dockerfiles, CI pipelines or server setup scripts still run pecl install, it’s time to plan a change. A new PHP RFC, Sunset PECL, proposes a firm timeline for shutting down pecl.php.net, and after feedback on the internals list the author shortened it on 11 November 2026: PECL would go read-only on 30 June 2027 and shut down on 31 December 2027. The replacement is PIE, the PHP Installer for Extensions. This guide explains the proposal and shows how to move your extension installs to PIE today.
What the RFC proposes
The RFC was opened for discussion by James Titcumb on 5 November 2026 and is still under discussion; it has not been voted on yet. It follows the 2025 RFC that adopted PIE and deprecated PECL “in messaging only”. The current text proposes:
- 4 January 2027: a banner on the PECL site announces the read-only date and links migration steps for extension authors.
- 30 June 2027: pecl.php.net becomes read-only. Nobody can log in or upload releases.
- Brownouts in 2027, getting longer each time: 3 hours on 3 September, 6 hours on 1 October, 24 hours on 5 November, and three days from 3 to 6 December. Downloads fail during brownouts.
- 31 December 2027: the PECL website shuts down and its repositories are archived.
The first draft had a shutdown date at the end of 2029. As the discussion thread shows, Rowan Tommins worried about serving unpatchable packages for two and a half years, Derick Rethans suggested shortening the timeline, and the author updated the RFC to one year overall. It also now says that if a serious vulnerability is found during the read-only phase, affected package versions may be removed manually.
The impact section is blunt: “PECL will stop working. PIE must be used going forward.”
Docker users: you may already be affected
As PHP News reports, the official PHP Docker images stopped shipping PECL with PHP 8.6 after docker-library/php#1654 was merged. The same change stopped compiling mbstring into the 8.6 images, so add docker-php-ext-install mbstring if your app needs it. If you’re building PHP 8.6 images (GA is planned for 19 November 2026), pecl install lines in those Dockerfiles need to change now, not in 2027.
PIE in one minute
PIE installs extensions using their Composer package names, resolved through Packagist. You can browse PIE-ready extensions on packagist.org/extensions or search from the command line. According to the RFC, PIE works with all PHP versions: the PHAR needs PHP 8.1 or newer, and the standalone executable ships with its own static PHP.
Install it manually:
# Download pie.phar from https://github.com/php/pie/releases, then:
gh attestation verify --owner php pie.phar # optional: verify the source
sudo cp pie.phar /usr/local/bin/pie
pie -V
PECL to PIE command cheat sheet
The PIE usage documentation includes a comparison table. The commands you’ll use most:
| PECL | PIE |
|---|---|
pecl install xdebug |
pie install xdebug/xdebug |
pecl upgrade xdebug |
pie install xdebug/xdebug |
pecl info xdebug |
pie info xdebug/xdebug |
pecl list |
pie show |
pecl search |
pie search <term> |
pecl download xdebug |
pie download xdebug/xdebug |
pecl build xdebug |
pie build xdebug/xdebug |
Find the right package name with search:
pie search redis
pie search xdebug
Version constraints use Composer syntax:
pie install "xdebug/xdebug:^3.4"
Need to target a different PHP install? Point PIE at its php-config:
pie install --with-php-config=/usr/bin/php-config8.3 xdebug/xdebug
Migrating a Dockerfile
PIE is published as a binary-only Docker image, so you can mount it only at build time and keep it out of your final image. This is adapted from the official docs:
FROM php:8.5-cli
RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin/pie \
export DEBIAN_FRONTEND="noninteractive"; \
set -eux; \
apt-get update; \
apt-get install -y --no-install-recommends unzip; \
pie install --no-cache xdebug/xdebug; \
apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false unzip; \
rm -rf /var/lib/apt/lists/*
# On PHP 8.6 images, also run: docker-php-ext-install mbstring
A few notes:
- PIE needs
unzip(or the zip extension) to extract archives, like Composer. - The
bintag is the latest stable release and is the one the docs recommend. Version tags like1.5-binalso exist if you want to pin. - Extensions that need system libraries still need those packages installed first, just as with PECL.
- If the extension isn’t enabled automatically, use
docker-php-ext-enableas you did before.
Let PIE read your composer.json
This is a nice upgrade over PECL. If your project’s composer.json declares extensions:
{
"require": {
"php": "^8.3",
"ext-curl": "*",
"ext-redis": "^6.3"
},
"require-dev": {
"ext-xdebug": "*"
}
}
run pie install in the project directory with no arguments. PIE checks each ext-* requirement, reports what’s already installed and offers to install the missing ones. In CI or production builds:
# Skip extensions that are only in require-dev (like xdebug)
pie install --no-dev
# Tell PIE which package provides a missing extension (PIE 1.5+)
pie install --select example_pie_extension=asgrim/example-pie-extension
The docs say that since PIE 1.6.0 a map of well-known extensions to package names is fetched automatically, so common extensions often resolve without --select. You can opt out with PIE_DISABLE_PACKAGE_MAP_FETCH=1.
Keeping extensions up to date
PIE can upgrade everything it installed, within the original version constraints:
pie upgrade
If you installed foo/bar:^1.0, pie upgrade will move you to new 1.x releases but never to 2.0. For a major jump, run pie install foo/bar:^2.0 explicitly.
For extension maintainers
If your extension ships only through PECL, the proposed dates matter most to you:
- From 30 June 2027 you couldn’t publish new PECL releases.
- From 31 December 2027 PECL couldn’t install anything at all.
Add a composer.json with the PIE metadata, publish to Packagist and check that pie install your/package works on Linux, macOS and Windows. The PIE repository’s documentation covers the details, and the January 2027 banner is planned to link migration steps.
Action checklist
- Search your repos for
pecl install,pecl upgradeandpecl channel-update. - Map each extension to its Packagist name with
pie search. - Update Dockerfiles, starting with any PHP 8.6 images.
- Declare required extensions as
ext-*incomposer.jsonand usepie install --no-devin builds. - Follow the RFC on the PHP wiki, since dates can change before the vote.
Takeaway
PECL’s retirement is now a calendar date, not a vague plan, and the proposed date moved two years closer. PIE already covers the everyday commands, works neatly in Docker, and can install extensions straight from composer.json. Switch your build scripts now and you won’t notice the brownouts at all.
