PECL is the standard channel for installing many PHP extensions that are not bundled directly with your PHP installation. If you need features such as caching, debugging, image processing, database drivers, or lower-level performance tools, PECL often provides the fastest path to adding them without compiling everything manually from source.
Installing PECL correctly depends on your operating system, PHP version, package manager, and development tools. A working setup usually requires PHP, the PHP development headers, a compiler toolchain, and the right configuration so installed extensions are loaded by the PHP runtime you actually use.
As an Amazon Associate I earn from qualifying purchases.
This guide walks through the practical setup process across Linux, macOS, and Windows, then shows how to install, enable, verify, troubleshoot, update, and remove PECL packages safely.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteWhat PECL Is and When You Need It
PECL, short for PHP Extension Community Library, is a distribution system for PHP extensions written primarily in C. These extensions add low-level capabilities to PHP that are not always included in the default PHP installation. Common examples include database drivers, caching clients, image processing tools, debugging extensions, serialization formats, and performance-related modules.
#1 Best Overall
PECL is closely related to PEAR, the older PHP Extension and Application Repository, but they serve different purposes. PEAR mainly distributes PHP libraries written in PHP, while PECL distributes compiled PHP extensions that must be built for your operating system, PHP version, and CPU architecture. When you install a PECL package, the tool usually downloads the extension source code, compiles it with your local PHP development tools, and places the resulting shared object file where PHP can load it.
How PECL fits into PHP extensions
PHP extensions are modules that expand what the PHP runtime can do. Some are bundled with PHP itself, such as json, mbstring, pdo, and openssl, depending on how PHP was packaged. Others are maintained separately and distributed through PECL. After installation, a PECL extension is typically enabled by adding an extension=... directive to a PHP configuration file such as php.ini or a file inside a PHP configuration directory like conf.d.
You need PECL when an application depends on an extension that is not already installed and is not available through your operating system’s package manager, or when the PECL version is newer than the packaged version. Frameworks, CMS plugins, queue workers, analytics tools, and high-performance APIs may require extensions such as redis, imagick, xdebug, mongodb, yaml, apcu, or protobuf.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Common situations where PECL is useful
- Adding Redis support: Install the
redisextension so PHP applications can communicate efficiently with a Redis server. - Enabling image processing: Use
imagickwhen an application requires ImageMagick features beyond PHP’s built-in GD extension. - Debugging PHP applications: Install
xdebugfor stack traces, step debugging, code coverage, and profiling during development. - Connecting to MongoDB: Use the
mongodbextension required by modern MongoDB PHP libraries. - Improving local caching: Install
apcufor fast in-memory user cache storage in a single-server PHP environment.
PECL is most useful on developer workstations, custom servers, containers, and hosting environments where you control the PHP configuration. On managed hosting platforms, you may not have permission to compile or enable extensions, so the hosting control panel or support team may need to provide them. In production, PECL should be used carefully: the installed extension must match the active PHP version, be compatible with your operating system, and be enabled for the correct runtime, such as PHP-FPM, Apache mod_php, or the command-line PHP binary.
Prerequisites for Installing PECL
Before installing PECL, confirm that your PHP environment includes the tools needed to compile and enable native extensions. PECL packages are commonly distributed as source code, so installation often requires more than the PHP runtime alone. A working setup typically includes PHP, the PHP development headers, a compiler toolchain, and permission to modify PHP configuration files.
Start by checking the PHP version and the active command-line binary. This matters because many systems have mulle PHP versions installed, especially development machines, hosting servers, and systems using third-party repositories. Run php -v to confirm the version, then use which php on Linux or macOS, or where php on Windows, to see which executable is being used. The PECL command should match the same PHP version you plan to run in your web server or CLI application.
Core requirements
- PHP installed: PECL installs extensions for PHP, so PHP must already be available on the system.
- PHP development package: Most PECL builds require phpize and PHP header files. On Debian or Ubuntu this is usually provided by php-dev or a versioned package such as php8.3-dev. On RHEL-based systems it is commonly php-devel.
- PEAR and PECL command-line tools: PECL is distributed with PEAR on many platforms. The command pecl version should return version details if it is already installed.
- Compiler and build tools: Linux systems usually need packages such as gcc, make, and related build utilities. macOS requires Xcode Command Line Tools. Windows generally uses precompiled DLLs instead of compiling through PECL.
- Administrative access: Installing extensions and editing PHP configuration usually requires sudo, administrator access, or write permission to PHP’s extension and configuration directories.
Package names vary by operating system and PHP source. On Debian and Ubuntu, you may need php-cli, php-dev, php-pear, and build-essential. On Fedora, Rocky Linux, AlmaLinux, or CentOS Stream, common packages include php-cli, php-pear, php-devel, gcc, and make. On macOS with Homebrew, PHP usually includes the necessary PHP tooling, but you may still need xcode-select –install for compilers and headers.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Configuration details to check first
- Loaded php.ini path: Use php –ini to find the configuration file used by PHP CLI.
- Extension directory: Use php -i and look for extension_dir to confirm where compiled extensions are stored.
- Thread safety and architecture: On Windows, match PHP version, architecture, compiler build, and thread-safety status when downloading extension DLLs.
- Web server PHP version: Apache, Nginx with PHP-FPM, and the CLI may use different PHP installations. Verify the version used by your application, not only the terminal.
It is also worth confirming network access before continuing. PECL downloads package metadata and source archives from online repositories, so restricted corporate networks, proxies, firewalls, or custom certificate policies can interrupt installation. If your environment uses a proxy, configure PEAR/PECL proxy settings before attempting package installation.
Once these prerequisites are in place, PECL can compile extensions reliably and place them where PHP can load them. Preparing the environment first prevents common failures such as missing phpize, unavailable header files, compiler errors, or extensions being installed for the wrong PHP version.
Installing PECL on Linux, macOS, and Windows
PECL is distributed with the PEAR command-line tooling, so installing PECL usually means installing the package that provides pear and pecl. The exact package name depends on your operating system and PHP source. Before running the commands below, confirm the PHP CLI version you intend to use with php -v, especially on systems with mulle PHP versions installed.
Rank #2
Linux installation
On Debian and Ubuntu-based distributions, install PECL through the PHP development packages and PEAR tooling. The development package is needed because many PECL extensions compile native code during installation.
- Debian or Ubuntu:
sudo apt update && sudo apt install php-pear php-dev build-essential - RHEL, CentOS, Rocky Linux, or AlmaLinux:
sudo dnf install php-pear php-devel gcc make - Older RHEL or CentOS systems:
sudo yum install php-pear php-devel gcc make - Fedora:
sudo dnf install php-pear php-devel gcc make - Arch Linux:
sudo pacman -S php php-pear base-devel
After installation, run pecl version to confirm the command is available. If your server uses a third-party PHP repository, such as Ondřej Surý packages on Ubuntu or Remi packages on RHEL-compatible systems, install the matching development package for that PHP version. For example, PHP 8.3 on Ubuntu may use php8.3-dev instead of the generic php-dev.
macOS installation
On macOS, the most common approach is to install PHP through Homebrew, which includes the required PEAR and PECL tooling for many PHP builds. Start by installing or updating Homebrew PHP:
brew updatebrew install phpphp -vpecl version
If pecl is not found after installing PHP with Homebrew, check that Homebrew’s binary path is loaded in your shell. Apple Silicon Macs commonly use /opt/homebrew/bin, while Intel Macs commonly use /usr/local/bin. You can inspect the active PHP binary with which php and the PECL binary with which pecl. Both should usually come from the same Homebrew prefix to avoid installing extensions for a different PHP build.
Windows installation
PECL support on Windows is different because most PHP extensions are distributed as precompiled .dll files rather than compiled locally through the PECL command. If you use a packaged stack such as XAMPP, WampServer, Laragon, or a manually installed PHP ZIP build, first check whether php.exe is available from Command Prompt or PowerShell with php -v.
Recommended Free Tools
| Platform | Primary install method | Check command |
|---|---|---|
| Debian or Ubuntu | apt install php-pear php-dev |
pecl version |
| RHEL-compatible Linux | dnf install php-pear php-devel |
pecl version |
| macOS | brew install php |
pecl version |
| Windows | Use matching extension DLLs or a PHP distribution that includes PECL tooling | php -v |
For Windows, download extensions from the official PECL Windows builds page when available, matching the PHP version, architecture, thread-safety mode, and compiler version shown by php -i. Place the DLL in PHP’s ext directory, then enable it in php.ini. Some Windows PHP distributions may include pecl.bat, but DLL installation is usually more reliable for typical local development setups.
Installing PHP Extensions with PECL
After PECL is available on your system, you can use it to download, compile, and install PHP extensions from the PECL repository. The basic command format is simple: run pecl install followed by the extension name. For example, to install the Redis extension used by many PHP applications for caching and queues, run pecl install redis. To install the MongoDB driver, run pecl install mongodb. PECL fetches the source package, checks its metadata, runs the build process, and places the compiled extension file in PHP’s extension directory.
Most PECL extensions require PHP development headers and build tools because they are compiled locally. On Linux, this usually means packages such as php-dev, php-devel, gcc, make, and related dependencies. On macOS, Xcode Command Line Tools are commonly needed. On Windows, PECL support is different because extensions are typically installed by downloading precompiled .dll files that match your PHP version, architecture, and thread-safety setting, rather than compiling with the same workflow used on Unix-like systems.
Basic PECL install commands
- Install the latest stable version:
pecl install redis - Install a specific version:
pecl install redis-6.0.2 - Install a beta release:
pecl install channel://pecl.php.net/package_name-beta - Search for packages:
pecl search redis - View package information:
pecl info redis - List installed PECL packages:
pecl list
Some extensions ask configuration questions during installation. For example, an extension may ask whether to enable optional features, link against a system library, or use a custom installation path. If you are unsure, the default answer is often suitable for a standard setup. For automated builds, such as Docker images or CI pipelines, you can pipe blank answers into PECL with printf "\n" | pecl install extension_name, although this should be used only when the defaults are known to work for your environment.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →For extensions that depend on external libraries, install those libraries before running PECL. For example, image, compression, database, and messaging extensions may need system-level development packages. If the installer fails with missing header files such as library.h not found, install the matching -dev or -devel package through your operating system’s package manager, then rerun the PECL command. This is common with extensions that integrate with native services rather than being pure PHP-facing modules.
Example extension installs
| Extension | Common use | Install command |
|---|---|---|
redis |
Redis caching, sessions, queues | pecl install redis |
mongodb |
MongoDB database driver | pecl install mongodb |
xdebug |
Debugging, profiling, coverage | pecl install xdebug |
imagick |
Image processing through ImageMagick | pecl install imagick |
When mulle PHP versions are installed, make sure PECL is tied to the PHP version used by your application. Check with which pecl, pecl config-show, and php -v. On systems with versioned PHP binaries, you may need commands such as phpize8.2, php-config8.2, or a version-specific PECL binary. Installing an extension for PHP 8.3 will not make it available to PHP 8.2, because each version uses its own API directory and compiled module compatibility.
Enabling and Verifying Installed Extensions
After PECL compiles and installs an extension, PHP still needs to load it at runtime. In many cases, the PECL installer prints a line such as extension=redis.so, extension=mongodb.so, or extension=imagick.so. That line must be added to the correct PHP configuration file. On Windows, the extension name usually ends in .dll, such as extension=php_redis.dll, while Linux and macOS typically use .so files.
First, find the active PHP configuration file for the environment you are configuring. The PHP CLI, Apache module, PHP-FPM, and a control panel stack may each use different configuration paths. Run the following command to see the CLI configuration location:
php --ini
The output shows the loaded php.ini file and the directory scanned for additional .ini files. If your system uses a scanned configuration directory, it is cleaner to create a separate file for the extension instead of editing the main php.ini. For example, on many Debian and Ubuntu systems, PHP modules are managed through files under /etc/php/8.3/mods-available/ and enabled per SAPI using helper commands. On RHEL-based systems, extension configuration files are often placed under /etc/php.d/.
Enable the extension in PHP configuration
Use the configuration style that matches your operating system and PHP installation. Replace the extension name and PHP version as needed:
- Generic Linux or macOS: add
extension=redis.soto the activephp.inior to a dedicated file such asconf.d/redis.ini. - Debian or Ubuntu: create
/etc/php/8.3/mods-available/redis.iniwithextension=redis.so, then runsudo phpenmod redis. - RHEL, AlmaLinux, Rocky Linux, or Fedora: create
/etc/php.d/40-redis.iniwithextension=redis.so. - macOS with Homebrew PHP: place the extension line in a file under the Homebrew PHP
conf.ddirectory, commonly shown byphp --ini. - Windows: confirm the compiled
.dllfile is in the PHPextdirectory, then add a line such asextension=php_redis.dlltophp.ini.
Some PECL extensions require extra system libraries or additional PHP directives. For example, an extension may need a path to a native library, a socket location, or feature-specific settings. Check the extension’s PECL page or upstream documentation if the extension loads but does not behave as expected.
Restart the relevant PHP service
Configuration changes do not always take effect immediately. Restart the service that runs PHP for your application. For Apache with mod_php, restart Apache. For Nginx or Apache using PHP-FPM, restart the PHP-FPM service. For CLI-only usage, open a new shell session or rerun the PHP command.
- Apache:
sudo systemctl restart apache2orsudo systemctl restart httpd - PHP-FPM:
sudo systemctl restart php8.3-fpmor the matching service name for your version - Homebrew PHP:
brew services restart php - Windows web server: restart IIS, Apache, or the PHP service used by your stack
Verify that PHP loaded the extension
The fastest CLI check is to list loaded modules and filter for the extension name:
php -m | grep redis
On Windows PowerShell, use:
php -m | Select-String redis
You can also inspect detailed extension information with:
php --ri redis
If the extension is loaded, PHP prints its version, configuration directives, and runtime status. For a web application, create a temporary PHP file containing <?php phpinfo();, open it in the browser, and search for the extension name. Delete that file after testing, since it exposes server paths, loaded modules, and configuration details.
Rank #4
| Check | Command or method | Expected result |
|---|---|---|
| Loaded in CLI | php -m |
Extension name appears in the module list |
| Extension details | php --ri extension_name |
Version and settings are displayed |
| Loaded in web PHP | phpinfo() |
Extension section appears in browser output |
If the extension appears in CLI but not in the browser, you are likely editing the CLI configuration instead of the web SAPI configuration. Compare php --ini with the Loaded Configuration File value shown in phpinfo(), then enable the extension in the configuration path used by the web server.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteCommon PECL Installation Errors and Fixes
PECL installation problems usually come from missing build tools, mismatched PHP versions, disabled development headers, or an extension that needs extra system libraries. Start by checking which PHP binary PECL is using, because servers often have mulle PHP versions installed. Run php -v, pecl version, and which php or where php on Windows to confirm that the command line environment matches the PHP version used by your web server.
Missing phpize or PHP development files
If PECL fails with an error such as phpize: command not found or Cannot find config.m4, the PHP development package is missing. On Debian or Ubuntu, install it with sudo apt install php-dev or a versioned package such as php8.3-dev. On RHEL, Rocky Linux, AlmaLinux, or Fedora, install php-devel. On macOS with Homebrew PHP, reinstall or relink PHP using brew reinstall php and make sure Homebrew’s bin directory is first in your shell path.
Compiler and build dependency failures
Errors mentioning make, gcc, cc, or build failed indicate that native compilation tools are unavailable. Install build-essential on Debian-based systems, Development Tools on RHEL-family systems, or Xcode Command Line Tools on macOS with xcode-select –install. Some extensions also require external libraries. For example, image, compression, database, and messaging extensions may need packages such as libjpeg-dev, zlib-devel, openssl-devel, or librabbitmq-dev before PECL can compile them.
- Permission denied: Use sudo pecl install extension_name on system PHP installations, or fix ownership if you manage PHP in a user-controlled prefix.
- No releases available: Update the PECL channel with pecl channel-update pecl.php.net, then retry the installation.
- Package requires newer PHP: Install an older compatible extension release, such as pecl install redis-5.3.7, or upgrade PHP.
- Cannot load shared object: Confirm that extension_dir points to the directory containing the compiled .so or .dll file.
Version mismatches between CLI and web PHP
A common situation is that php -m shows the extension, but the application still reports it as missing. This usually means PECL installed the extension for the command line PHP, while Apache, Nginx with PHP-FPM, or another runtime uses a different PHP build. Compare php –ini with a browser-based phpinfo() page, then add the extension to the correct php.ini or conf.d directory. After changing configuration, restart the service, such as sudo systemctl restart php8.3-fpm or sudo systemctl restart apache2.
Free tools Windows power users keep installed
One-click scans. No signup required.
Windows-specific DLL loading issues
On Windows, PECL packages are often installed by downloading the correct DLL rather than compiling from source. Match the DLL to your PHP version, architecture, compiler build, and thread safety mode. For example, PHP 8.3 x64 non-thread-safe requires a different file than PHP 8.3 x64 thread-safe. If PHP reports that the module could not be found, place the DLL in the configured ext directory, add any required dependency DLLs to the PHP directory or system path, then enable it with a line such as extension=php_extensionname.dll.
When an installation fails, rerun PECL with a clean terminal session and capture the full output instead of only the final error line. The first missing header, library, or version conflict usually appears earlier in the log. After applying a fix, reinstall the package, restart the relevant PHP service, and verify with php -m, php –ri extension_name, or phpinfo().
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Updating, Removing, and Managing PECL Packages
After PECL is working, ongoing maintenance is straightforward but should be handled carefully, especially on production servers. PECL extensions are compiled against the PHP version and build environment available at install time, so changes to PHP itself can affect whether an extension continues to load correctly. A good maintenance routine includes checking installed packages, reviewing available upgrades, updating extensions during planned maintenance windows, and removing packages that are no longer used.
Checking Installed PECL Packages
Use the PECL command-line tool to list extensions installed through PECL. This helps you distinguish PECL-managed extensions from extensions installed through your operating system package manager or bundled with PHP.
- List installed PECL packages:
pecl list - Show package details:
pecl info redis - Check available upgrades:
pecl list-upgrades - View PECL configuration:
pecl config-show
The package name shown by PECL is not always identical to the extension name used in php.ini. For example, the package may be installed as redis, while PHP loads it with a directive such as extension=redis.so on Linux or macOS, or extension=php_redis.dll on Windows.
Updating PECL Extensions
To update a single extension, run the upgrade command with the package name. For example, pecl upgrade redis downloads the latest available release, rebuilds it, and replaces the currently installed PECL package. To upgrade all PECL packages that have newer versions available, use pecl upgrade without a package name. After upgrading, restart your web server or PHP process manager so the new binary is loaded.
- PHP-FPM: restart the relevant PHP-FPM service, such as
sudo systemctl restart php8.3-fpm. - Apache with mod_php: restart Apache, such as
sudo systemctl restart apache2orsudo systemctl restart httpd. - CLI-only usage: open a new shell session and confirm the extension version with
php --ri extension_name.
If the server runs mulle PHP versions, confirm that you are using the matching PECL binary before upgrading. For example, pecl may point to PHP 8.2 while the application uses PHP 8.3. In that case, use the version-specific command if available, such as pecl8.3, or call PECL through the correct PHP installation path provided by your package manager or hosting environment.
Removing PECL Packages Cleanly
To uninstall a PECL package, use pecl uninstall package_name. This removes the compiled extension files managed by PECL, but it may not remove the configuration line that loads the extension. After uninstalling, check the active PHP configuration files and remove or comment out directives such as extension=imagick.so or extension=php_imagick.dll. Leaving those lines in place can cause startup warnings such as “Unable to load dynamic library.”
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →- Run
pecl uninstall package_name. - Remove the matching
extension=...entry fromphp.inior a scannedconf.dfile. - Restart PHP-FPM, Apache, or the relevant service.
- Verify removal with
php -mandphp --ri package_name.
Maintenance Best Practices
Before upgrading extensions on production systems, record the currently installed versions with pecl list and keep a copy of related PHP configuration files. Test upgrades in a staging environment when possible, particularly for extensions that connect to external services, handle image processing, provide caching, or affect request performance. If an upgrade fails after a PHP version change, reinstalling the extension with PECL often resolves binary compatibility issues because the extension is rebuilt for the current PHP headers and API version.
For stable deployments, avoid mixing installation methods for the same extension. If redis, imagick, or xdebug was installed from the operating system repository, do not install a second copy through PECL unless you deliberately remove the packaged version and update the configuration. Keeping one source of truth for each extension makes upgrades easier, reduces duplicate load errors, and simplifies troubleshooting when PHP reports startup or module conflicts.
Frequently Asked Questions
Do I need PECL if PHP is already installed on my system?
You only need PECL when you want to install PHP extensions that are not already included or enabled in your PHP installation. Common examples include Redis, MongoDB, Xdebug, APCu, and imagick. If the extension is available through your operating system’s package manager, that may be easier to maintain than installing it through PECL.
How do I know which php.ini file to edit after installing a PECL extension?
Run php --ini from the command line to see the configuration files used by PHP CLI. For a web server, create a temporary PHP file containing phpinfo(); and check the “Loaded Configuration File” value in the browser. CLI PHP and web PHP may use different php.ini files, so make sure you enable the extension in the one used by your application.
What should I do if PECL says phpize is missing?
The phpize command is usually provided by PHP development packages, not the basic PHP runtime. On Debian or Ubuntu, install php-dev; on RHEL-based systems, install the matching PHP development package; on macOS with Homebrew, make sure your PHP package is correctly installed and in your PATH. After installing the development package, rerun the PECL install command.
Why does the extension install successfully but not show up in php -m?
The extension may be installed but not enabled in the active PHP configuration. Add the correct extension=extension_name.so line to the appropriate php.ini or conf.d file, then restart PHP-FPM, Apache, or your web server. Also confirm that the PECL command and the PHP binary you are checking belong to the same PHP version.
How do I update or remove an extension installed with PECL?
Use pecl upgrade extension_name to update an installed extension and pecl uninstall extension_name to remove one. After uninstalling, delete or disable the related extension entry from your PHP configuration so PHP does not try to load a missing file. Restart your web server or PHP-FPM service after making configuration changes.
Bottom Line
PECL is the standard path for adding many powerful PHP extensions, but a smooth setup depends on having the right PHP version, development tools, package manager, and configuration files in place. Once PECL is installed, you can add extensions, enable them in the correct php.ini, restart your web server or PHP-FPM, and verify everything with php -m, php --ri, or a PHP info page.
Your next step is to install one test extension, confirm it loads in both CLI and web contexts, and document the exact commands for your operating system and PHP version. From there, keep extensions updated carefully, review compatibility before PHP upgrades, and remove anything your applications no longer need.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
