Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

'pecl: command not found' on macOS

Errorpecl: command not found

Short 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.

  • Applies to macOS 15, Homebrew on Apple silicon, PHP 8.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out whether PHP and Homebrew are on your PATH at all.

    which php
    echo "$PATH"
    brew --prefix
  2. 2Match what you see, then jump to its fix

    1. 1which 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. 2pecl 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. 3pecl is missing or fails on a current PHPPECL is deprecated: install the extension with PIEFix

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 | head

2Fix

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 ~/.zshrc

3Verify

which php now points to a Homebrew path.

which php

Confirmed by docs.brew.sh

Did this fix it?

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 --prefix

2Fix

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 pecl

Confirmed by docs.brew.sh

Did this fix it?

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 --version

2Fix

Install PIE, then use pie install. Microsoft's own driver instructions use the same path with PIE for macOS.

pie install microsoft/sqlsrv

3Verify

The extension appears in the module list.

php -m | grep sqlsrv

Confirmed by php.net

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.