Setup & site building · Guide
How to Fix WP Command Not Found: Causes and Fixes

Short answer
The error means your shell cannot find WP-CLI. Install it by downloading the phar file, making it executable and moving it to a folder on your PATH as wp, or add the folder where WP-CLI already lives to your PATH, then open a new terminal and run wp --info.
Key takeaways
- WP-CLI does not come with WordPress; you install it separately.
- The phar file must be executable and named wp on your PATH.
- Composer and Homebrew installs need their bin folders on the PATH.
- Windows needs a small wp.bat wrapper.
- Avoid running wp as root; use the site's file owner instead.
Why do you get “wp: command not found”?
The shell cannot find a program called wp, which means WP-CLI is either not installed, installed under another name, not executable, or sitting in a folder that is not on your PATH.
wp is the command for WP-CLI, the official command-line tool for managing WordPress. It does not ship with WordPress itself, so a fresh server or laptop will not have it.
The exact message varies by system. On Linux and macOS you usually see wp: command not found or zsh: command not found: wp. On Windows you see that wp is not recognised as an internal or external command.
The fix depends on which of these situations you are in. The steps below start with a quick check, then cover each install method.
How do you check whether WP-CLI is installed?
Run which wp on Linux or macOS, or where wp on Windows, and check whether a wp-cli.phar file exists anywhere on the machine.
If which wp prints nothing, the shell cannot see a wp command on your PATH. That does not always mean WP-CLI is missing, only that the shell cannot find it.
Search for the phar file next:
find ~ /usr/local /opt -name "wp-cli.phar" 2>/dev/null
If the file turns up, WP-CLI is downloaded but not set up as a command. Skip to the section on making it executable and moving it onto your PATH.
If nothing turns up, install WP-CLI using one of the methods below.
Pick the method that matches your setup. The plain phar download works almost everywhere, Homebrew suits Macs, and Composer suits developers who already manage PHP tools with it.
Do not mix methods on the same machine if you can avoid it. Two copies in different folders make it hard to know which one runs, and one may be much older than the other.
Also check that PHP itself works, because WP-CLI is a PHP program:
php -v
If php is not found either, install PHP or add it to your PATH first. Our guide on checking the PHP version on your host helps on shared hosting.
How do you install WP-CLI the standard way?
Download the wp-cli.phar file, test it with PHP, make it executable and move it to /usr/local/bin/wp so the shell can find it as wp.
These are the steps from the official WP-CLI installation guide:
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
php wp-cli.phar --info
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
wp --info
The second line confirms the file runs under your PHP. The chmod line marks it as executable. The mv line renames it to wp and puts it in a folder that is on the PATH for most systems.
If the last command prints WP-CLI and PHP details, the error is fixed.
If curl is not available, wget with the same URL works too. Some locked-down servers block outbound downloads, in which case download the file on your own computer and upload it by SFTP.
If php wp-cli.phar --info fails with an error about PHP version or missing extensions, update PHP first. WP-CLI needs a supported PHP version, and our guide to which PHP version to use for WordPress helps you choose.
What if you do not have sudo access?
Put the file in a folder inside your home directory, such as ~/bin, and add that folder to your PATH.
mkdir -p ~/bin
mv wp-cli.phar ~/bin/wp
chmod +x ~/bin/wp
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
On macOS with zsh, use ~/.zshrc instead of ~/.bashrc. Open a new terminal window afterwards and run wp --info.
How do you fix it when WP-CLI is installed but not on the PATH?
Add the folder that contains the wp file to your PATH in your shell profile, or create a symlink to it from a folder that is already on the PATH.
First, see what your PATH contains:
echo $PATH
If the folder holding wp is not listed, either add it to your profile file as shown above, or link it:
sudo ln -s /path/to/wp-cli.phar /usr/local/bin/wp
Remember that changes to ~/.bashrc or ~/.zshrc only apply to new terminal sessions. Run source on the file or open a new window.
Login shells sometimes read ~/.bash_profile or ~/.profile instead of ~/.bashrc. If the PATH change works in one terminal but not over SSH, add the same export line to the profile file your login shell reads.
To see which wp the shell finds once it works, run type wp. It prints the full path, which is useful when several copies exist.
Why does “wp” work for you but not with sudo?
The sudo command often uses a restricted PATH, so a wp file in your home folder or a Composer folder will not be found when you run sudo wp.
You usually should not run WP-CLI as root anyway. WP-CLI warns against it, because files it creates will be owned by root and the web server may not be able to change them later.
Run commands as the user that owns the WordPress files instead:
sudo -u www-data wp plugin list --path=/var/www/html
Swap www-data for your server's web user and the path for your WordPress folder. Our guide to setting correct file permissions explains why ownership matters.
How do you fix it after installing with Composer?
Composer installs WP-CLI into its global vendor/bin folder, so you must add that folder to your PATH before wp will work.
The Composer install looks like this:
composer global require wp-cli/wp-cli-bundle
Find Composer's global bin folder with:
composer global config bin-dir --absolute
Add the printed path to your PATH in your shell profile. It is often ~/.composer/vendor/bin or ~/.config/composer/vendor/bin.
Learn more about Composer on the Composer website and in our guide to using Composer with WordPress.
How do you fix it on macOS with Homebrew?
Install WP-CLI with brew install wp-cli, then make sure Homebrew's bin folder is on your PATH, which Homebrew's installer usually sets up for you.
On Apple silicon Macs, Homebrew uses /opt/homebrew/bin. On Intel Macs it uses /usr/local/bin.
If brew itself is not found, Homebrew's shell setup lines are missing from your profile. Re-run the lines the Homebrew installer printed at the end of installation.
How do you fix it on Windows?
Download wp-cli.phar to a folder such as C:\wp-cli, create a wp.bat file next to it that calls PHP with the phar, and add that folder to the Windows PATH.
The wp.bat file needs two lines:
@ECHO OFF
php "C:/wp-cli/wp-cli.phar" %*
Then add C:\wp-cli to the PATH in System Properties > Environment Variables, and make sure the folder holding php.exe is on the PATH too.
Close and reopen Command Prompt or PowerShell. Many Windows users find it easier to run WP-CLI inside WSL, where the Linux steps above apply.
How do you fix it on shared hosting, Docker or local tools?
On hosting, WP-CLI may be preinstalled under a different path or not offered at all; in Docker and local apps, you often have to run wp inside the right container or site shell.
| Environment | What to check |
|---|---|
| Shared or managed hosting | Ask support or check docs; WP-CLI may be preinstalled or unavailable |
| Docker | Run wp inside the WordPress or a WP-CLI container, not on the host |
| Local apps such as Local | Use the app's site shell option so the right PHP and PATH load |
| CI pipelines | Install WP-CLI as a build step before calling wp |
Many managed WordPress hosts include WP-CLI on SSH. If wp is missing, try /usr/local/bin/wp or check the host's help pages before installing your own copy.
Some hosts do not allow running binaries from your account. In that case you cannot use WP-CLI there, and need to work through wp-admin or ask the host.
In Docker setups, the official WordPress image does not include WP-CLI, but a separate CLI image does. Run commands with docker compose run against that service, or install WP-CLI inside your own image as a build step.
In scheduled tasks such as cron jobs, the PATH is often much shorter than in your interactive shell. Use the full path to wp in crontab lines, as shown in our guide to running WordPress cron from the server.
How do you confirm WP-CLI works with your site?
Change into your WordPress folder and run wp core version; if it prints a version number, WP-CLI can find PHP, the command and your site.
If you get This does not seem to be a WordPress installation, you are in the wrong folder. Use --path to point at the right one.
If you get database errors, check the details in wp-config.php. Our guide on where to find wp-config.php helps you locate it.
Keep WP-CLI updated with wp cli update when you installed the phar file. Composer and Homebrew installs update through those tools.
What can you do once WP-CLI works?
With WP-CLI running, you can update plugins, export databases, search and replace URLs, manage users and run cron from the terminal much faster than through wp-admin.
The full list lives in the WP-CLI commands reference. Our pick of useful WP-CLI commands is a good starting point.
If you plan to move a site, see how to migrate WordPress with WP-CLI.
PHP's own command-line documentation is useful if you need to pass memory limits or other options when running the phar directly.
Frequently asked questions
Does WordPress come with WP-CLI?
No. WP-CLI is a separate tool maintained by the WordPress project. Some hosts preinstall it on their servers, but a fresh server, a laptop or a basic hosting account usually needs it installed before the wp command works.
Why does wp work in one terminal but not another?
Each shell reads its own profile file. If you added WP-CLI to your PATH in the bash profile but the other terminal uses zsh, or a new window has not loaded the change yet, it will not find wp. Update the right profile file and reopen the terminal.
Can I run WP-CLI without installing it globally?
Yes. You can run the phar file directly with PHP, for example php wp-cli.phar followed by the command, from any folder. It works the same way, just with a longer command, which is handy on hosts where you cannot change the PATH.
Is it safe to run wp commands as root?
WP-CLI warns against it. Commands run as root can create files owned by root that the web server cannot change, and any malicious code in plugins would run with full rights. Run WP-CLI as the user that owns the WordPress files instead.
How do I update WP-CLI?
If you installed the phar file, run wp cli update, adding sudo if it lives in a system folder. If you installed through Composer or Homebrew, use their update commands instead so the package manager keeps track of the version.
Sources
- Installing WP-CLI WP-CLI Handbook
- WP-CLI WP-CLI
- WP-CLI Commands WordPress Developer Resources
- Composer Composer
- Command line options PHP Manual
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


