'pecl: command not found' on macOS
pecl: command not foundShort answer
On a Mac the command is usually found only when Homebrew's bin folder is on your PATH. Add the line brew shellenv prints to your shell config. PECL itself is deprecated: PHP's manual recommends PIE, installed once, then pie install vendor/package.
Fix it fast
1Find out which cause you have
Find out whether PHP and Homebrew are on your PATH at all.
which php echo "$PATH" brew --prefix2Match what you see, then jump to its fix
- 1
which php shows /usr/bin/php or nothing, and brew --prefix works only with the full pathHomebrew's prefix is not on PATH in this shellFix - 2
pecl works in Terminal but not in an editor's built-in task or an appThe tool runs from a GUI app that does not inherit your shell PATHFix - 3
pecl is missing or fails on a current PHPPECL is deprecated: install the extension with PIEFix
- 1
What does the error look like?
pecl: command not found
Cause 1 of 3
Homebrew's prefix is not on PATH in this shell
1Check
Homebrew's default prefix on Apple silicon is /opt/homebrew. If its bin folder is missing from PATH, tools it installed are not found.
ls /opt/homebrew/bin | head2Fix
Add the shellenv line to your shell config as Homebrew's installation page describes (for zsh, ~/.zshrc), then open a new terminal.
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc3Verify
which php now points to a Homebrew path.
which phpConfirmed by docs.brew.sh
Cause 2 of 3
The tool runs from a GUI app that does not inherit your shell PATH
1Check
The Homebrew FAQ says GUI apps on macOS do not have Homebrew's prefix in their PATH by default.
brew --prefix2Fix
Start the app from a terminal, or set the path for all GUI apps as the FAQ shows, then restart the Mac.
sudo launchctl config user path "$(brew --prefix)/bin:${PATH}"3Verify
After a reboot the app finds the command.
which peclConfirmed by docs.brew.sh
Cause 3 of 3
PECL is deprecated: install the extension with PIE
1Check
The PHP manual says PECL is deprecated and PIE replaces it. PIE installs extensions from Packagist's extension repository by their vendor/package name.
php /usr/local/bin/pie --version2Fix
Install PIE, then use pie install. Microsoft's own driver instructions use the same path with PIE for macOS.
pie install microsoft/sqlsrv3Verify
The extension appears in the module list.
php -m | grep sqlsrvConfirmed by php.net
How do I stop it coming back?
- Keep the shellenv line in your shell config so every new terminal has the same PATH.
- Use the same PHP executable to install and to run: check which php before each install.
- Prefer PIE for new extension installs.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack end
Apache returns 403 when a URL contains %3F
a request like /page%3Fname=test is refused while /page?name=test works
Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.
2 causes, each with a fixBack end
Apache returns 500 with Premature end of script headers
500 Internal Server Error
Apache ran your script, but the script printed no valid HTTP header before its output.
3 causes, each with a fixBack end
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fixBack end
AWS SDK for PHP cannot get credentials from the instance profile metadata server
Error retrieving credentials from the instance profile metadata server.
The SDK tries the EC2 instance metadata service when it has no valid credentials from anywhere earlier in its chain.
4 causes, each with a fixBack end
AWS SDK for PHP rejects requests: the signature is from the future
Signature not yet current: {date} is still later than {date}
AWS compares the timestamp in your signed request with its own clock.
2 causes, each with a fix