Master Installing PHP Extensions with PIE: Step‑by‑Step Guide for PHP 8.1+

Overview

PIE is the official PHP Extension Installer released by the PHP team. It requires PHP 8.1 or newer to run, but can install extensions for any PHP version that is already installed on the system.

Installing PIE

Download

wget https://github.com/php/pie/releases/download/0.1.0/pie.phar

After downloading, the file is saved as pie.phar.

Add to PATH

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

Using PIE

php pie.phar <command>
# or
pie <command>

For example, to display help:

/usr/local/php-8.2.14/bin/php pie.phar --help
# or
pie --help

The help output lists commands, options, and usage examples.

Supported Extensions

The list of extensions that can be installed with PIE is available at https://packagist.org/extensions.

Installing an Extension with PIE

Use the install command followed by the package name. Example for the example_pie_extension Redis extension:

php pie.phar install example/example-pie-extension

Installing the APCu Extension

To demonstrate, install the apcu extension. The package repository is https://packagist.org/packages/apcu/apcu.

sudo /usr/local/php-8.2.14/bin/php pie.phar install --with-php-config=/usr/local/php-8.2.14/bin/php-config apcu/apcu

After installation, add extension=apcu to php.ini, then verify:

/usr/local/php-8.2.14/bin/php -m | grep apcu
/usr/local/php-8.2.14/bin/php --ri apcu

Note

PIE requires PHP 8.1 or higher; the example uses PHP 8.2.14.

If the system default PHP is 7.4, you must invoke the specific PHP binary (e.g., /usr/local/php-8.2.14/bin/php) when running PIE.

When installing extensions for a non‑default PHP version, use the --with-php-config option to point to the correct php-config executable.

Add extension to php.ini

vim /usr/local/php-8.2.14/etc/php.ini
# add
extension=apcu

Version Constraints and Stability

You can specify a version constraint when installing an extension:

pie install <vendor>/<package>:<version-constraint>