How to install php extension using pecl for specific php version, when several php versions installed in system?

How to install php extension using pecl for specific php version, when several php versions installed in system?

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Avoiding Cross-Version Confusion When Installing PECL Extensions on Multi-PHP Systems

Managing multiple PHP versions on a single server is a common requirement, particularly when migrating legacy applications to newer runtimes or when running different services against different minor versions. However, the ecosystem of PHP extensions often complicates this setup. While package managers like apt handle core binaries cleanly by maintaining separate directories for each version (e.g., /usr/lib/php/7.0/... vs /usr/lib/php/5.6/...), the PECL extension installer operates with a single global state that frequently ignores which PHP binary you are currently active.

This discrepancy leads to frustrating scenarios where pecl install reports that an extension is already installed, even when it was only compiled for a different version. The root cause lies in how PECL determines its configuration file and search paths. By default, PECL reads from /etc/php.ini, a global file that often contains directives relevant to multiple versions or becomes the primary reference point regardless of which specific php-cli binary is invoked.

Understanding the Default PECL Behavior

When you run pecl install libevent while your system's active PHP version is set to 7.0, PECL checks its internal list of installed packages. This list is derived from the configuration file it reads first. If that configuration file points to a location shared between versions or if the global state persists across sessions without explicit reconfiguration, PECL assumes the extension exists.

In many Ubuntu setups involving PPA installations, the php.ini file might be symlinked or configured in a way that confuses the tool. For instance, an entry like extension_dir="/usr/lib/php/20131226/" (PHP 5.6's date-based directory) inside a global config will cause PECL to look for extensions in the wrong place when targeting PHP 7.0, which expects directories like /usr/lib/php/20151012/.

Manually Configuring PECL for Specific Versions

To resolve this, you must explicitly tell PECL where to find the configuration file and extension directory for the specific version you intend to install into. You cannot rely solely on update-alternatives switching your shell's php command; that only affects which binary runs when you type php. The installation tool itself needs its own context.

You can create a small script to switch PECL's configuration targets before running any install command. For PHP 7.0, the necessary setup looks like this:

sudo update-alternatives --set php /usr/bin/php7.0
sudo pecl config-set php_ini /etc/php/7.0/cli/php.ini
sudo pecl config-set ext_dir /usr/lib/php/20151012/
sudo pecl config-set bin_dir /usr/bin/
sudo pecl config-set php_bin /usr/bin/php7.0
sudo pecl config-set php_suffix 7.0

After running these commands, pecl list should reflect the state of PHP 7.0 only. If it previously showed packages installed for PHP 5.6, they will disappear from the list because PECL is now looking in a different namespace. You can then proceed with:

sudo pecl install libevent
sudo pecl install amqp

The Trade-Offs and Alternative Approaches

While manually configuring PECL works, it requires repeating these steps every time you switch contexts or if the configuration is not persistent across reboots. A cleaner approach often involves using package managers that respect version isolation from the start.

For many standard extensions like amqp or redis, the recommended path on Debian-based systems is to use apt directly:

sudo apt-get install php7.0-amqp
sudo apt-get install php7.0-libevent

This method bypasses PECL entirely, ensuring that binaries and shared objects land directly in the version-specific library directories (/usr/lib/php/20151012/) without needing to manipulate PECL's internal state variables. It avoids the risk of mixing development versions with stable releases or encountering dependency hell where a PECL extension compiled for one minor version refuses to load on another.

Why This Matters for Production Stability

Relying on manual PECL configuration introduces fragility. If the php_ini path changes, or if a system update shifts the ext_dir, your installation commands will fail or install into the wrong place. Furthermore, mixing extensions installed via PECL with those installed via apt can lead to conflicts if they define overlapping functions or classes, even if they live in different directories.

If you are building a production environment where multiple PHP versions coexist, the safest strategy is to limit manual PECL usage to version-specific scenarios that lack official packages. For everything else, prefer the distribution's package manager. This ensures that your extension list remains clean, version-aware, and resilient to system updates.

Our network