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 →pecl: command not found has two usual causes: the package that supplies PECL is not installed, or the executable exists in a directory outside your shell’s PATH. On Debian and Ubuntu, install php-pear; on Fedora and RHEL-family systems, install the release’s php-pear package. If the package is already present, find the PEAR binary directory, add it to PATH, refresh the shell’s command cache, and verify with pecl version.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
The procedure below separates package problems from PATH problems, checks that PECL and the PHP CLI belong to the same installation, and explains what to do after PECL is working.
As an Amazon Associate I earn from qualifying purchases.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsWhat the error means
PECL is the command-line installer for PHP extensions. The Debian pecl(1) documentation describes the command as the installer for PECL extensions, while PEAR documentation expects both pear and pecl to be callable from a shell.
When a shell prints pecl: command not found, it has not found an executable with that name. That does not necessarily mean PECL itself is broken. The failure is normally one of these:
#1 Best Overall
- The distribution package that provides PECL, normally named
php-pear, is not installed. - The package is installed, but its PEAR
bindirectory is not inPATH. - The executable was added recently and the current shell has a stale command lookup cache.
- Several PHP installations are present, and PEAR belongs to a different installation than the PHP CLI you are running.
Diagnose the installation before changing it
Run the following commands as your normal user. Use sudo only for package installation or editing system-owned files.
-
Identify the distribution and PHP CLI
cat /etc/os-release php -v command -v php/etc/os-releaseidentifies the distribution and release family.php -vreports the CLI version, andcommand -v phpshows which PHP executable your shell is actually using. Record these results before installing anything, because a manually installed PHP and a distribution PHP can coexist.Crashes, 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 minutePC 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 & 11Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Check whether the shell can already see PECL
command -v pecl type -a peclIf either command prints a path, PECL is discoverable and the original error may have come from a different shell, script environment, or stale command cache. If both commands produce no path, continue with the package-file checks.
-
Check package contents
On Debian or Ubuntu, inspect the files installed by
php-pear:dpkg -L php-pear | grep '/pecl$'On Fedora or an RHEL-family distribution, use:
rpm -ql php-pear | grep '/pecl$'A printed path proves that the package is installed and shows where its executable resides. If the package manager reports that the package is not installed, use the distribution-specific installation section below. If a path is printed but
command -v peclremains empty, the issue is PATH discovery rather than package ownership.
Install the package that provides PECL
Debian and Ubuntu
Debian documents php-pear as the package that provides the pecl command. Refresh package metadata, then install it:
sudo apt update
sudo apt install php-pearThe PEAR installation documentation notes that distributor-supplied PHP may require PEAR to be installed separately, so having PHP itself installed does not guarantee that pecl is present. After installation, run command -v pecl. If it still prints nothing, continue to the PATH steps instead of repeatedly reinstalling the package.
Rank #2
Fedora and RHEL-family systems
Fedora packaging uses a php-pear package for PEAR and PECL tooling. Install the package with the package manager used by your release. On current Fedora systems, that is commonly:
sudo dnf install php-pearOn releases that still use the older command name, the equivalent is:
sudo yum install php-pearUse the package manager configured for your particular release and repositories. Installing development tools is not required merely to make the pecl command appear. You need the matching PHP development package and compiler toolchain when you later build an extension from source with PECL.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Repair PATH when php-pear is already installed
PEAR’s documentation requires its binary directory to be included in the shell’s PATH. The package-file commands above show the exact location of pecl; use the directory containing that file, not the file path itself.
Test the fix in the current shell
Temporarily prepend the directory that contains pecl to PATH. For example, if the package listing shows that the executable is in $HOME/.local/bin, run:
export PATH="$HOME/.local/bin:$PATH"
command -v pecl
pecl versionReplace the example directory with the directory shown on your system. This change lasts only for the current shell, which makes it useful for testing before editing a startup file.
Make the change persistent
Add the same export PATH=... line to the startup file used by your shell. For Bash, ~/.profile is appropriate for login shells and ~/.bashrc is commonly read for interactive non-login shells. Other shells have their own startup files. Open a new shell after saving the file, or reload the relevant file explicitly.
Rank #3
Do not add the executable itself to PATH; add only its containing directory. Keep the existing value by appending :$PATH, otherwise you can hide standard commands.
Refresh Bash’s command cache
Bash can remember that a command was previously missing. Clear that cache after installing PEAR or changing PATH:
hash -r
command -v peclStarting a new terminal has the same effect. If a new shell finds PECL but the old one does not, the problem was the stale lookup rather than the package.
Verify that PECL and PHP belong together
Once the command is discoverable, verify both the PECL client and its extension registry:
command -v pecl
pecl version
pecl listpecl version should start successfully, and pecl list should return the installed PECL extensions (an empty list is valid on a new installation). If command -v pecl prints a path but pecl version fails with a PHP interpreter or library error, the problem is no longer command discovery.
Compare the PHP executable and version used by the shell with the installation that supplied PEAR:
command -v php
php -v
command -v pecl
pecl versionA common cause is mixing a distribution PHP with a separately installed PHP under another prefix. Install php-pear for the PHP installation you intend to use, or adjust PATH so the matching PHP and PEAR tools are selected together. Avoid assuming that the first executable found in PATH is the one used by a web server; web and command-line SAPIs can load different configuration files.
Install an extension after PECL works
The PHP manual documents this basic form:
pecl install extnameReplace extname with the extension’s PECL package name. PECL downloads the extension source, compiles it, and installs the resulting shared object, normally an .so file, into PHP’s extension directory.
Free tools Windows power users keep installed
One-click scans. No signup required.
Provide build prerequisites when compilation requires them
Because PECL compiles source code, a successful command lookup does not guarantee a successful build. If compilation stops with missing headers, a compiler error, or an unavailable build tool, install the development package that matches the PHP CLI and the toolchain required by your distribution. The development package must correspond to the same PHP installation whose php executable you verified earlier.
Enable the extension for the SAPI that needs it
Installing the shared object does not automatically make every PHP process load it. Enable the module in the applicable php.ini or an SAPI-specific conf.d file. CLI scripts and web requests can use different configuration trees, so check each one separately when necessary.
After enabling it, verify the CLI configuration with:
php -mFor a web application, restart the web service or PHP process manager after changing its configuration so that it loads the new module. The exact service name depends on your distribution and server setup.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Choose the right fix
| Situation | Primary action | What it resolves |
|---|---|---|
php-pear is absent |
Install php-pear with the distribution package manager |
Places the PEAR and PECL commands on the system |
Package files include pecl, but command -v pecl is empty |
Add the package’s PEAR bin directory to PATH, then run hash -r or open a new shell |
Lets the shell discover an existing executable |
pecl version reports PHP or library errors |
Align the PEAR package, PHP CLI, and PATH to the same PHP installation | Fixes mismatched interpreters and libraries |
| You are installing a new extension for a project | Consider PIE, the PHP Installer for Extensions, instead of beginning a new PECL workflow | Uses the installation method now recommended by PHP documentation |
Troubleshoot the common failure branches
The package cannot be found
If apt install php-pear, dnf install php-pear, or the equivalent command says that no package is available, confirm the distribution from /etc/os-release and check that the repositories for that release are enabled. Package names and repository availability are distribution-specific. Do not install a package built for a different release simply because its name looks similar.
The package is installed but no executable is listed
Run the package-file query again. If dpkg -L php-pear or rpm -ql php-pear does not show a path ending in /pecl, the package database may not describe the installation you are using, or a different PHP/PEAR installation is active. Check which package manager owns the PHP executable and avoid mixing files from unrelated installation prefixes.
The path is correct but the command still fails
Confirm that the directory, rather than only the file, appears in PATH:
printf '%sn' "$PATH"
command -v peclThen run hash -r and open a new shell. If a script or service still cannot find PECL, remember that non-interactive shells and services may use a restricted PATH and may not read your interactive startup files. Configure the environment for that specific execution context instead of changing unrelated system files.
pecl version starts but extension installation fails
Separate command availability from compilation. The first proves that the PECL client is installed; the second may require a matching PHP development package, compiler, headers, and libraries. Read the first missing dependency in the build output, install the dependency for the same PHP release, and rerun the install. If the extension is not compatible with that PHP release, consult the extension’s compatibility information rather than repeatedly changing PATH.
The extension is installed but a web application cannot use it
Check the configuration used by the web SAPI, not only the CLI. Enable the module in that SAPI’s applicable configuration directory and restart the web service or PHP process manager. A successful php -m check confirms the CLI only; it does not prove that a web request loads the same module.
PECL’s current status and the PIE alternative
The PHP manual and PECL homepage currently state that PECL is deprecated and that PHP Installer for Extensions (PIE) replaces PECL and is recommended for installing extensions. That status matters when starting a new project: use the current PHP-recommended workflow where your distribution and project support it.
Deprecation does not remove the immediate repair described here. Existing Linux distributions may still package and support pecl, and older deployment scripts may depend on it. Installing php-pear or correcting PATH remains the appropriate response when an existing command fails with command not found. Treat migration to PIE as a separate decision from repairing shell discovery.
Recommended Free Tools
Quick Recap
Final verification checklist
cat /etc/os-releaseidentifies the intended Linux release.php -vandcommand -v phpidentify the PHP CLI you plan to use.command -v peclprints the PECL executable’s path.- The package query confirms which installed package owns that executable.
- The executable’s directory is present in
PATH. hash -rhas been run, or a new shell has been opened.pecl versionandpecl listrun without interpreter or library errors.- Any extension installed with PECL is enabled in the correct CLI or web-SAPI configuration.
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.
