PIE is the official installer for PHP extensions, which replaces PECL (which is now deprecated). PIE is distributed as a PHAR, just like Composer, and works in a similar way to Composer, but it installs PHP extensions (PHP Modules or Zend Extensions) to your PHP installation, rather than pulling PHP packages into your project or library.
PIE comes in two flavours. Primarily, a PHAR file that we recommend for most cases, but requires PHP 8.1. Alternatively, we publish a self-contained executable version of PIE for Linux (amd64/arm64), OSX (arm64), and Windows (amd64).
On Linux/OSX, if any build tools needed are missing, PIE will ask if you would like to automatically install them first (as of PIE 1.4.0).
On Windows, you do not need any build toolchain installed, since PHP extensions for Windows are distributed as pre-compiled packages containing the extension DLL.
- Download
pie.phareither: - Verify the PHAR's source with
gh attestation verify --owner php pie.phar - You may then invoke PIE with
php pie.phar <command>
Further installation details can be found in the usage docs.
This documentation assumes you have moved pie.phar into your $PATH, e.g.
/usr/local/bin/pie on non-Windows systems or created an alias in your shell RC file.
This will install PIE into /usr/local/bin/pie on a non-Windows system:
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
Tip
For usage in a Docker image build, we have a recommended usage example in usage#example-of-pie-working-in-a-dockerfile.
You can install an extension using the install command. For example, to
install the example_pie_extension extension, you would run:
$ pie install asgrim/example-pie-extension š„§ PHP Installer for Extensions (PIE) 1.4.0, from The PHP Foundation This command may need elevated privileges, and may prompt you for your password. You are running PHP 8.5.3 Target PHP installation: 8.5.3 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.5) Found package: asgrim/example-pie-extension:2.0.9 which provides ext-example_pie_extension Extracted asgrim/example-pie-extension:2.0.9 source to: /path/to/example-pie-extension phpize complete. Configure complete with options: --with-php-config=/usr/bin/php-config8.5 Build complete: /path/to/example-pie-extension/modules/example_pie_extension.so Install complete: /usr/lib/php/20250925/example_pie_extension.so ā Extension is enabled and loaded in /usr/bin/php8.5 $
As of PIE 1.5 you can install multiple extensions at the same time. Note that if multiple extensions share the same configure options, this command will fail.
pie install foo/great-extension bar/another-extension
When in your PHP project, you can install any missing top-level extensions:
$ pie install
š„§ PHP Installer for Extensions (PIE) 1.4.0, from The PHP Foundation
You are running PHP 8.5.0
Target PHP installation: 8.5.0 nts, on Linux/OSX/etc x86_64 (from /usr/local/bin/php)
Checking extensions for your project asgrim/demo-php-project (path: /demos/demo-php-project)
requires: ext-curl:* ā
Already installed
requires: ext-example_pie_extension:^2.0 š« Missing
The following packages may be suitable, which would you like to install:
[0] None
[1] asgrim/example-pie-extension: Example PIE extension
> 1
example_pie_extension> You are running PHP 8.5.0
example_pie_extension> Target PHP installation: 8.5.0 nts, on Linux/OSX/etc x86_64 (from /usr/local/bin/php)
example_pie_extension> Found package: asgrim/example-pie-extension:2.0.9 which provides ext-example_pie_extension
example_pie_extension> Extracted asgrim/example-pie-extension:2.0.9 source to: /path/to/example-pie-extension
example_pie_extension> phpize complete.
example_pie_extension> Configure complete with options: --with-php-config=/usr/local/bin/php-config
example_pie_extension> Build complete: /path/to/example-pie-extension/modules/example_pie_extension.so
example_pie_extension> Install complete: /usr/local/lib/php/extensions/no-debug-non-zts-20250925/example_pie_extension.so
example_pie_extension> ā
Extension is enabled and loaded in /usr/local/bin/php
Finished checking extensions.
Important
If you are running PIE in a non-interactive shell (for example, CI, a
container), the --allow-non-interactive-project-install is no longer
functional. You must specify --select flags for each missing package, e.g.:
pie install \ --select example_pie_extension=asgrim/example-pie-extension \ --select redis=phpredis/phpredis
A list of extensions that support PIE can be found on https://packagist.org/extensions.
- If you have an idea, question, or need help, please use the Discussions.
- Please check with us first before contributing new features - it may be something we're already working on, as the PHP Foundation is actively developing this too, and there are new features already in the pipeline...
- If you have a bug to report, please use the Issues.
If you are an extension maintainer wanting to add PIE support to your extension, please read extension-maintainers.
The full documentation for PIE can be found in usage docs.