WP-CLI is a command-line interface for WordPress. It lets you install plugins, manage users, run database operations, and more — all from a terminal, without touching the WordPress admin interface. This guide covers installation on Linux, macOS, and Windows, plus verification and troubleshooting steps for the most common failure modes.
TL;DR: On Linux or macOS (phar method), download the Phar file, make it executable, and move it to your PATH. On macOS, the fastest route is
brew install wp-cli. On Windows, install Cygwin or use WSL2, then follow the Linux steps. Runwp --versionto confirm the install worked.
Platform and Method Quick Reference
| Platform | Recommended method | Alternative |
|---|---|---|
| Linux | curl (phar) | Composer |
| macOS | Homebrew (brew install wp-cli) |
curl (phar) |
| Windows (Cygwin) | curl (phar) in Cygwin terminal | — |
| Windows (WSL2) | Follow the Linux steps inside WSL2 | — |
WP-CLI can also be installed as a Composer package; see the official WP-CLI documentation for require wp-cli/wp-cli instructions.
Prerequisites
- PHP 5.4 or later
- WordPress 3.7 or later
- SSH access to your server for Linux installations
- Administrator privileges for Windows installations
Installation on Linux
- Download WP-CLI:
Open a terminal window and download the WP-CLI Phar file using curl:
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.pharIn our testing on Ubuntu 22.04 LTS, the curl method completes in under a minute on a standard server connection.
- Make WP-CLI Executable:
Make the downloaded Phar file executable:
chmod +x wp-cli.phar- Move WP-CLI to Bin Directory:
Move the executable to a directory in your PATH. The /usr/local/bin directory is the standard location:
sudo mv wp-cli.phar /usr/local/bin/wp- Verify WP-CLI Installation:
Check that WP-CLI is installed correctly by displaying its system information:
wp --infoInstallation on macOS
macOS is the primary development environment for many WordPress developers. The Homebrew method is the simplest path and keeps WP-CLI up to date automatically.
Install via Homebrew (recommended)
If you have Homebrew installed, run:
brew install wp-cliAfter installation, confirm it works:
wp --versionInstall via Phar (without Homebrew)
If you prefer the manual method, the Linux Phar steps work on macOS without modification:
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
wp --versionInstallation on Windows
- Download WP-CLI:
Visit the WP-CLI GitHub page and download the latest Phar file from:
https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar- Download and Install Cygwin:
WP-CLI requires a Unix-like terminal. Download and install Cygwin from the official site:
https://www.cygwin.com/During installation, ensure that you install the curl, php, php-curl, php-mbstring, openssl, and openssh packages.
- Move WP-CLI to the Cygwin Directory:
Move the wp-cli.phar file to your Cygwin home directory, usually C:cygwin64homeYour_User.
- Make WP-CLI Executable:
Open Cygwin terminal and navigate to your home directory using cd ~. Then make the Phar file executable:
chmod +x wp-cli.phar- Move WP-CLI to Bin Directory:
Move the executable to your PATH. The /usr/bin directory within Cygwin is the standard location:
mv wp-cli.phar /usr/bin/wp- Verify WP-CLI Installation:
Check that WP-CLI is installed correctly by displaying its system information:
wp --infoVerify the Installation
After installing WP-CLI by any method, confirm it is working with two commands.
Check the version:
wp --versionThe command outputs a version string such as WP-CLI x.y.z. Check the WP-CLI releases page to confirm you have the latest version.
Run a basic health check:
wp doctor checkThis checks for common configuration issues. Run it from within a WordPress directory to get site-specific results. The doctor command is part of the wp-cli/doctor-command package, which requires separate installation — see the wp-cli/doctor-command README for setup instructions.
Troubleshooting
From WP STAGING support tickets, the most common cause of WP-CLI install failures is PATH misconfiguration. Below are the top failure modes and their fixes.
wp: command not found after installation (Linux/macOS)
The WP-CLI Phar was not placed in a directory in your $PATH. Confirm where wp was moved:
which wpIf the command returns nothing, the binary is not in your PATH. Add /usr/local/bin to your PATH by editing ~/.bashrc or ~/.zshrc:
export PATH="$PATH:/usr/local/bin"
source ~/.bashrcThen retry wp --version.
PHP not found in PATH (Windows / Cygwin)
WP-CLI requires PHP accessible from the terminal. In Cygwin, verify PHP is installed by running php --version. If it returns an error, re-run the Cygwin installer and add the php package.
Permission denied on the Phar file (Linux/macOS)
If you see a "Permission denied" error when moving the file to /usr/local/bin, prefix the command with sudo:
sudo mv wp-cli.phar /usr/local/bin/wpIf sudo is unavailable (such as on shared hosting), move the file to a user-writable directory (e.g., ~/bin/) and add that directory to your PATH instead.
PHP version mismatch
WP-CLI requires PHP 5.4 or later. Run php --version to check the version your terminal resolves to. If you have multiple PHP versions installed, the version WP-CLI picks up is determined by your PATH order. In most cases we see this issue on servers running a PHP version below the 5.4 minimum — upgrading PHP to meet the requirement resolves it. See php.net/manual/en/install.php for PHP installation guidance.
Conclusion
Now that WP-CLI is installed, you can start using it to manage your WordPress site from the command line. The official WP-CLI documentation covers the full command reference and handbook.
