How to Install and Configure WP-CLI on Ubuntu/Debian (2025 Complete Guide)

WP-CLI is the official command-line interface for WordPress that lets you manage your WordPress installations without using a web browser. If you’re managing multiple WordPress sites or want to automate repetitive tasks, WP-CLI is an absolute game-changer.

In this comprehensive guide, you’ll learn how to install and configure WP-CLI on Ubuntu and Debian Linux systems from scratch. Whether you’re a beginner or experienced developer, this step-by-step tutorial will have you up and running in less than 10 minutes.

What is WP-CLI and Why Use It?

WP-CLI is a powerful command-line tool for managing WordPress installations. Instead of clicking through the WordPress admin panel, you can execute commands directly from your terminal.

Key Benefits of WP-CLI

Time Savings: Update all plugins across 50 sites with one command instead of logging into each site manually.

Automation: Schedule backups, updates, and maintenance tasks with cron jobs.

Bulk Operations: Perform actions on hundreds of posts, users, or sites simultaneously.

Remote Management: Manage WordPress sites via SSH without needing FTP or admin panel access.

DevOps Integration: Integrate WordPress into your CI/CD pipelines and deployment scripts.

Real-World Use Cases

• Update all WordPress core, plugins, and themes across 100+ sites in minutes
• Import/export databases during migrations
• Generate test content for development environments
• Automate WordPress installation and configuration
• Search and replace URLs after moving sites
• Manage WordPress Multisite networks efficiently

According to WordPress.org, over 43% of all websites use WordPress. If you manage even 2-3 WordPress sites, WP-CLI will save you hours every week.

Prerequisites

Before installing WP-CLI, ensure your system meets these requirements:

System Requirements

• Operating System: Ubuntu 18.04+ or Debian 9+ (this guide focuses on these distributions)
• PHP: Version 7.4 or higher (WordPress 6.0+ requirement)
• SSH Access: Terminal access to your server
• WordPress: An existing WordPress installation (or plan to install one)
• Root/Sudo Access: Permission to install system packages

Check Your PHP Version

First, verify you have PHP installed and check the version:

php -v

You should see output like:

PHP 8.1.2 (cli) (built: Jan 15 2025 10:30:45)
Copyright (c) The PHP Group
Zend Engine v4.1.2

If PHP is not installed or the version is below 7.4, install or update it:

# Ubuntu/Debian
sudo apt update
sudo apt install php-cli php-mbstring php-xml php-mysql -y

The php-cli, php-mbstring, and php-xml extensions are required for WP-CLI to function properly.

Check for Existing WordPress Installation (Optional)

If you already have WordPress installed, note the installation path. Common locations:

• /var/www/html
• /var/www/yourdomain.com/public_html
• /home/username/public_html

You’ll need this path to run WP-CLI commands later.

Installing WP-CLI on Ubuntu/Debian

There are several methods to install WP-CLI. We’ll use the official recommended method: downloading the Phar (PHP Archive) file.

Step 1: Download WP-CLI

Download the latest WP-CLI Phar file using curl:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

Alternative: If you don’t have curl installed, use wget:

wget https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

This downloads wp-cli.phar to your current directory.

Step 2: Verify the Phar File Works

Before installation, test that the Phar file is working:

php wp-cli.phar --info

You should see output showing WP-CLI information:

OS:     Linux 5.15.0-58-generic #64-Ubuntu SMP x86_64
Shell:  /bin/bash
PHP binary:    /usr/bin/php8.1
PHP version:   8.1.2
php.ini used:  /etc/php/8.1/cli/php.ini
MySQL binary:  /usr/bin/mysql
MySQL version: mysql  Ver 8.0.31-0ubuntu0.22.04.1

If you see this output, WP-CLI is working correctly.

Step 3: Make the File Executable

Add executable permissions to the Phar file:

chmod +x wp-cli.phar

Step 4: Move to System Path

Move the Phar file to a directory in your system PATH so you can run it from anywhere:

sudo mv wp-cli.phar /usr/local/bin/wp

Now you can run WP-CLI using the wp command instead of php wp-cli.phar.

Step 5: Verify Installation

Confirm WP-CLI is installed correctly:

wp --info

If you see the WP-CLI information output, congratulations! WP-CLI is successfully installed.

Expected output:

OS:     Linux 5.15.0-58-generic #64-Ubuntu SMP x86_64
Shell:  /bin/bash
PHP binary:    /usr/bin/php8.1
PHP version:   8.1.2
WP-CLI version: 2.9.0

Verifying Your Installation

Let’s run a few basic commands to ensure everything works properly.

Check WP-CLI Version

wp cli version

Output:

WP-CLI 2.9.0

Get Help

View available WP-CLI commands:

wp help

This displays a comprehensive list of all WP-CLI commands organized by category.

Test with a WordPress Installation

If you have WordPress installed, navigate to your WordPress directory and check the installation:

cd /var/www/html
wp core version

Output:

6.4.2

This confirms WP-CLI can successfully communicate with your WordPress installation.

Common Issue: If you get “Error: This does not seem to be a WordPress installation,” you’re either not in a WordPress directory or the path is incorrect. Make sure you’re in the root WordPress directory containing wp-config.php.

Configuring WP-CLI

WP-CLI can be configured globally or per-project using configuration files. This allows you to set default parameters and customize behavior.

Global Configuration File

Create a global config file in your home directory:

mkdir -p ~/.wp-cli
nano ~/.wp-cli/config.yml

Add basic configuration:

# ~/.wp-cli/config.yml

# Disable color output (useful for logs)
color: true

# Set default user for commands that require one
user: admin

# Quiet mode (suppress informational messages)
quiet: false

# Path to WordPress installation (optional, useful if you manage one main site)
path: /var/www/html

# Apache/Nginx modules directory
apache_modules: /usr/lib/apache2/modules

Save and exit (CTRL+X, then Y, then Enter in nano).

Project-Specific Configuration

For project-specific settings, create a wp-cli.yml file in your WordPress root directory:

cd /var/www/html
nano wp-cli.yml

Add project-specific configuration:

# /var/www/html/wp-cli.yml

# Specify the WordPress path (useful for non-standard structures)
path: wp

# Disable email sending during commands
# (prevents notification emails during bulk operations)
skip-plugins:
  - disable-emails

# Set default user for content operations
user: editor

# URL of the WordPress site (for proper link generation)
url: https://yourdomain.com

Important: The project-specific wp-cli.yml takes precedence over the global ~/.wp-cli/config.yml file.

Useful Configuration Options

Here are some additional configuration options you might find useful:

# Require confirmation for destructive operations
require:
  - confirmation

# Set custom command directory for your own commands
require:
  - /path/to/custom-commands.php

# HTTP request timeout (default: 30 seconds)
http-timeout: 60

# Set debug mode
debug: false

Learn more about configuration in the official WP-CLI config documentation.

Setting Up Command Aliases

WP-CLI aliases let you create shortcuts for frequently-used commands, making your workflow more efficient.

Creating Bash Aliases

Add these to your ~/.bashrc or ~/.bash_aliases file:

nano ~/.bashrc

Add these useful aliases at the end of the file:

# WP-CLI Aliases
alias wpcli='wp'
alias wpv='wp core version'
alias wpu='wp core update'
alias wppu='wp plugin update --all'
alias wptu='wp theme update --all'
alias wpdb='wp db export'
alias wpsearch='wp search-replace'
alias wpflush='wp cache flush'
alias wplist='wp plugin list'

Save and reload your bash configuration:

source ~/.bashrc

Now you can use shortcuts like:

wpv          # Check WordPress version
wppu         # Update all plugins
wpflush      # Clear cache

WP-CLI Native Aliases

WP-CLI also supports its own alias system for remote sites. Edit your config file:

nano ~/.wp-cli/config.yml

Add site aliases:

# ~/.wp-cli/config.yml

# Define site aliases
@production:
  ssh: user@production-server.com/var/www/html

@staging:
  ssh: user@staging-server.com/var/www/staging

@local:
  path: /var/www/html

Now you can run commands on remote sites:

# Update plugins on production
wp @production plugin update --all

# Export database from staging
wp @staging db export

# Check version on local
wp @local core version

This is incredibly powerful for managing multiple WordPress installations. Read more about WP-CLI aliases in the official handbook.

Updating WP-CLI

WP-CLI should be updated regularly to get new features, bug fixes, and security patches.

Check for Updates

wp cli check-update

Update to Latest Stable Version

wp cli update

Update to Nightly Build (Unstable)

For testing or if you need bleeding-edge features:

wp cli update --nightly

Warning: The nightly build may be unstable. Only use it for development/testing environments.

Verify New Version

After updating, confirm the new version:

wp cli version

Update Frequency

• Production servers: Update monthly or when security patches are released
• Development/staging: Update whenever a new stable version is available
• Check release notes: Review WP-CLI GitHub releases before updating production

Troubleshooting Common Issues

Issue 1: “wp: command not found”

Problem: After installation, running wp returns “command not found.”

Solutions:

1. Verify the file is in your PATH:

which wp

2. If nothing is returned, the file might not be in /usr/local/bin. Check if that directory is in your PATH:

echo $PATH

3. If /usr/local/bin isn’t in your PATH, add it to ~/.bashrc:

echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc
source ~/.bashrc

4. Alternatively, move wp to /usr/bin instead:

sudo mv /usr/local/bin/wp /usr/bin/wp

Issue 2: “Failed to get PHP binary path”

Problem: WP-CLI can’t find the PHP binary.

Solution: Specify the PHP binary path explicitly:

wp --path=/usr/bin/php8.1 core version

Or add it to your config file:

# ~/.wp-cli/config.yml
php: /usr/bin/php8.1

Find your PHP binary path:

which php

Issue 3: Permission Denied Errors

Problem: WP-CLI commands fail with permission errors.

Solutions:

1. Run commands as the web server user (usually www-data on Ubuntu/Debian):

sudo -u www-data wp plugin list

2. Or adjust file ownership:

sudo chown -R www-data:www-data /var/www/html

Important: Never run WP-CLI as root in production. Always use the appropriate web server user.

Issue 4: “This does not seem to be a WordPress installation”

Problem: WP-CLI doesn’t recognize your WordPress installation.

Solutions:

1. Ensure you’re in the WordPress root directory containing wp-config.php:

ls -la wp-config.php

2. If WordPress is in a subdirectory, specify the path:

wp --path=/var/www/html/wordpress core version

3. Or set the path in your config file (see Configuring WP-CLI section).

Issue 5: Memory Limit Errors

Problem: Commands fail with “Allowed memory size exhausted” errors.

Solution: Increase PHP memory limit:

php -d memory_limit=512M /usr/local/bin/wp plugin update --all

Or permanently increase it in php.ini:

sudo nano /etc/php/8.1/cli/php.ini

Find and modify:

memory_limit = 512M

Restart PHP if needed:

sudo systemctl restart php8.1-fpm

Need More Help?

• Official WP-CLI Documentation
• WP-CLI GitHub Issues
• WordPress Stack Exchange
• WP-CLI Community Slack

Next Steps

Now that WP-CLI is installed and configured, you’re ready to start managing WordPress from the command line!

Essential Commands to Learn Next

1. 20 Essential WP-CLI Commands Every WordPress Developer Should Know – Master the most important commands
2. WP-CLI Config Files: Best Practices – Advanced configuration techniques
3. Automate WordPress Backups with WP-CLI – Build your first automation script

Recommended Learning Path

Week 1: Practice basic commands

• wp core version, wp plugin list, wp theme list
• Learn wp help [command] to explore documentation

Week 2: Database operations

• Export/import databases: wp db export, wp db import
• Search and replace: wp search-replace

Week 3: Automation basics

• Write simple bash scripts using WP-CLI
• Set up cron jobs for automated tasks

Week 4: Advanced techniques

• Custom WP-CLI commands
• Integration with deployment pipelines

Join the WPCLI Mastery Community

Want to master WordPress automation and save 10+ hours per week?

Join our free email course and get:

• Free WordPress backup automation script
• Weekly WP-CLI tips and tricks
• Early access to WPCLI Mastery course ($99 early bird pricing)

Conclusion

Installing WP-CLI on Ubuntu and Debian is straightforward and takes less than 10 minutes. Once installed, you’ll have a powerful tool that can save you hours of manual WordPress administration work.

The key steps we covered:

1. Download the WP-CLI Phar file
2. Make it executable and move to system PATH
3. Verify installation with wp --info
4. Configure global and project-specific settings
5. Set up command aliases for efficiency
6. Keep WP-CLI updated regularly

With WP-CLI installed, you’re now equipped to manage WordPress sites like a DevOps professional. The commands you learn will compound over time—what takes hours in the WordPress admin panel can often be done in seconds with WP-CLI.

Ready to level up? Check out our complete WP-CLI command reference or start automating your WordPress backups.

Have questions about installing WP-CLI? Drop a comment below, and I’ll help you troubleshoot!

Share this guide with other WordPress developers who could benefit from WP-CLI.