Neste guia, explicamos como instalar o WP-CLI passo a passo no Debian, Ubuntu, Fedora, RHEL, AlmaLinux, Rocky Linux, macOS e Windows (via WSL).

Este artigo também cobre a instalação do PHP, MySQL, extensões necessárias e verificações preliminares completas. Siga cada etapa em ordem, especialmente em um servidor novo ou em uma instalação limpa do sistema operacional.

Antes de Começar

Esta é a Parte 2 da série WP-CLI. Se você ainda não leu a Parte 1, comece por lá.

Ela explica o que é WP-CLI, por que profissionais o utilizam e quais planos de hospedagem o suportam.

Lista de Verificação de Pré-requisitos

Antes de baixar o WP-CLI, seu sistema precisa de cinco itens em ordem. Se algum deles estiver faltando, o WP-CLI falhará na instalação ou lançará erros fatais no momento em que você executar seu primeiro comando. Siga esta lista de verificação de cima para baixo.

Pré-requisito 1: Um Ambiente UNIX-like

O WP-CLI roda nativamente em Linux, macOS e FreeBSD. No Windows, use WSL (Subsistema Windows para Linux). O WP-CLI não funciona no Prompt de Comando nativo do Windows ou no PowerShell.

Confirme se seu shell funciona:

whoami
pwd

Ambos os comandos devem retornar saída sem erros. Se funcionarem, seu ambiente está pronto.

Pré-requisito 2: Acesso SSH

O WP-CLI precisa de acesso ao terminal do seu servidor. Em uma máquina local, isso já está disponível. Em um servidor remoto, você precisa de SSH enabled em seu plano de hospedagem.

Verifique se o acesso SSH está funcionando:

echo "SSH is working"

Se você vir essa linha impressa de volta, você tem o acesso necessário. Se não tiver certeza se seu plano de hospedagem inclui SSH, consulte a seção de Requisitos de Hospedagem na Parte 1 desta série.

Pré-requisito 3: PHP 7.2.24 ou Superior com Extensões Necessárias

Se este for um servidor novo ou uma instalação limpa do SO, o PHP pode não estar presente. Execute esta verificação primeiro:

php --version

Se você vir "command not found", instale o PHP antes de qualquer outra coisa.

Você precisa do PHP 7.2.24 ou superior (este é o mínimo exato de acordo com a documentação oficial). Se sua versão for mais antiga, atualize o PHP antes de continuar.

Instalar PHP com extensões necessárias no Ubuntu / Debian:

sudo apt update
sudo apt install php php-cli php-mysql php-curl php-xml php-mbstring php-zip php-gd php-intl php-bcmath

Fedora / RHEL / CentOS / AlmaLinux / Rocky Linux:

sudo dnf install php php-cli php-mysqlnd php-curl php-xml php-mbstring php-zip php-gd php-intl php-bcmath

openSUSE:

sudo zypper install php8 php8-cli php8-mysql php8-curl php8-xml php8-mbstring php8-zip php8-gd php8-intl php8-bcmath

macOS (via Homebrew):

brew install php

Nota: A maioria das extensões necessárias já está incluída por padrão no macOS.

Após a instalação, confirme se o PHP está pronto:

php --version
php -m | grep -E 'mysqli|curl|xml|mbstring|zip|gd|intl'

Ambas as verificações devem retornar saída antes de você passar para a próxima etapa.

Ao consultar as extensões do PHP, você deve ver o nome de cada extensão impresso. Se alguma estiver faltando na saída, instale o pacote específico da versão para essa extensão e execute a verificação novamente.

Aqui está o que cada extensão faz para que você saiba exatamente por que ela é necessária:

Pré-requisito 4: MySQL ou MariaDB em Execução e Acessível

O WordPress armazena tudo (conteúdo, configurações, usuários e opções) em um banco de dados. Sem um servidor de banco de dados em execução, wp config create e wp core install falharão imediatamente com um erro de conexão.

O WordPress recomenda MySQL 8.0+ ou MariaDB 10.6+ como uma base segura e moderna para desempenho e segurança. Para qualquer nova instalação, use MySQL 8.4 LTS ou MariaDB 10.11 LTS. Ambos têm longas janelas de suporte.

Verificar se um Servidor de Banco de Dados já está Instalado

mysql --version
# or
mariadb --version

Se você vir "command not found" para ambos, instale um agora.

Instalar MySQL

Debian / Ubuntu / Linux Mint:

sudo apt update
sudo apt install mysql-server

RHEL / CentOS / AlmaLinux / Rocky Linux:

sudo dnf install mysql-server

Instalar MariaDB (Recomendado como Substituto)

Debian / Ubuntu / Linux Mint:

sudo apt update
sudo apt install mariadb-server

Fedora / RHEL / CentOS / AlmaLinux / Rocky Linux:

sudo dnf install mariadb-server

openSUSE:

sudo zypper install mariadb

macOS (via Homebrew):

brew install mariadb

Iniciar e Habilitar o Serviço

# For MySQL
sudo systemctl start mysql
sudo systemctl enable mysql
# For MariaDB
sudo systemctl start mariadb
sudo systemctl enable mariadb

A flag enable faz o serviço iniciar automaticamente toda vez que seu servidor reinicia. Sem ela, você precisa iniciar o banco de dados manualmente cada vez.

Executar o Assistente de Instalação Segura

Recomendado para qualquer ambiente que não seja Docker ou local:

# For MySQL
sudo mysql_secure_installation
# For MariaDB
sudo mariadb-secure-installation

Isso remove bancos de dados de teste padrão, desabilita o login root remoto e define uma senha root forte. Leva cerca de dois minutos e melhora significativamente a segurança do seu banco de dados.

Criar o Banco de Dados e o Usuário do WordPress

sudo mysql -u root -p

Em seguida, dentro do prompt do MySQL/MariaDB, execute estes comandos SQL:

CREATE DATABASE wordpress CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'wpuser'@'localhost' IDENTIFIED BY 'StrongPassword123';
GRANT ALL PRIVILEGES ON wordpress.* TO 'wpuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Substitua os seguintes pelos seus próprios valores:

  • wordpress - o nome do banco de dados de sua preferência (ex: mysite_db).
  • wpuser - o nome de usuário do banco de dados de sua preferência.
  • StrongPassword123 - uma senha forte e única. Nunca use uma senha simples em um servidor ativo.

A configuração CHARACTER SET utf8mb4 garante que o WordPress lide corretamente com caracteres internacionais, emojis e símbolos especiais desde o início. A linha FLUSH PRIVILEGES instrui o servidor de banco de dados a recarregar suas tabelas de permissões imediatamente.

Verificar a Conexão com o Banco de Dados

Antes de prosseguir, confirme se o novo usuário pode realmente se conectar:

mysql -u wpuser -p wordpress

Se isso abrir o prompt do MySQL sem erros, seu banco de dados está pronto. Digite exit para sair.

Por que usar 127.0.0.1 em vez de localhost às vezes: Quando você passa --dbhost=localhost, o PHP se conecta via um arquivo de soquete Unix. Se o caminho desse soquete for diferente entre o PHP e o MySQL no seu sistema, você receberá o erro 2002 "No such file or directory". Usar --dbhost=127.0.0.1 força o PHP a usar uma conexão TCP, que ignora completamente o soquete. Mude para 127.0.0.1 se localhost lançar esse erro.

Pré-requisito 5: WordPress 4.9 ou Superior

O WP-CLI requer WordPress 4.9 ou posterior. Versões mais antigas que o último lançamento do WordPress podem ter funcionalidade degradada. Isso não é uma preocupação para novas instalações, pois baixar o núcleo do WordPress com wp core download sempre puxa a versão estável mais recente. No entanto, se você estiver executando o WP-CLI em um site existente mais antigo, verifique sua versão do WordPress primeiro:

wp core version

Se a versão for inferior a 4.9, atualize o WordPress antes de confiar no WP-CLI:

wp core update

Verificação Preliminar Completa

Execute todas as quatro verificações antes de baixar o WP-CLI. Cada linha deve retornar uma saída limpa, sem erros, antes de prosseguir.

# 1. Confirm PHP version is 7.2.24 or higher
php --version
# 2. Confirm all required extensions are loaded
php -m | grep -E 'mysqli|curl|xml|mbstring|zip|gd|intl|bcmath'
# 3. Confirm MySQL or MariaDB is running
sudo systemctl status mysql    # or: sudo systemctl status mariadb
# 4. Confirm you can log into the database with the WordPress user
mysql -u wpuser -p wordpress -e "SELECT 'Connection OK';"

Todas as quatro verificações devem passar limpas. Assim que passarem, baixe o WP-CLI.

Passo 1: Verificar Acesso SSH

Antes de baixar o WP-CLI, faça uma verificação final rápida para confirmar que sua sessão de shell está ativa e você está no lugar certo no servidor:

whoami   # shows which user you are running as
pwd      # shows which directory you are currently in

Ambos os comandos devem retornar saída sem erros. Se você estiver em um servidor remoto, certifique-se de estar conectado via SSH antes de continuar. Se estiver trabalhando localmente, por exemplo, dentro de um contêiner Docker ou em um ambiente Linux local, você já tem acesso e pode ir direto para o Passo 2.

Passo 2: Baixar o WP-CLI

Baixe o último lançamento estável do WP-CLI com:

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

Ou use wget se curl não estiver disponível em seu sistema:

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

Para quem não sabe, um arquivo PHAR é uma aplicação PHP autocontida.

Verificar a Assinatura do PHAR

Esta etapa é recomendada para servidores de produção e ambientes preocupados com segurança. Ela confirma que o arquivo baixado não foi adulterado.

Baixe o arquivo de assinatura:

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

Em seguida, verifique-o contra a chave pública do WP-CLI:

gpg --keyserver keyserver.ubuntu.com --recv-keys 63AF7AA15067C05616FDDD88A3A2E8F226F0BC06
gpg --verify wp-cli.phar.asc wp-cli.phar

Um arquivo válido retorna Good signature from "WP-CLI (Signing Key)". Se a verificação falhar, exclua o arquivo PHAR e baixe-o novamente. Não instale um arquivo que falhe na verificação de assinatura.

Passo 3: Verificar o Download

Teste se o arquivo baixado funciona corretamente antes de instalá-lo em todo o sistema:

php wp-cli.phar --info

Isso deve exibir informações da versão do WP-CLI e sua configuração do sistema, caminho do binário PHP, versão do PHP e detalhes do SO. Se você vir essa saída, o arquivo é válido e está pronto para instalação.

Passo 4: Tornar Globalmente Acessível

Dê permissões executáveis ao arquivo e, em seguida, mova-o para o caminho do seu sistema para que você possa executar wp de qualquer diretório:

chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

Passo 5: Confirmar a Instalação

Verifique se o comando wp funciona de qualquer lugar do seu sistema:

wp --info

Se você vir informações de versão e sistema, o WP-CLI está totalmente instalado e pronto para uso. Esta é a saída que você deve esperar:

OS:	Linux 7.0.0-15-generic #15-Ubuntu SMP PREEMPT_DYNAMIC Wed Apr 22 16:06:43 UTC 2026 x86_64
Shell:	/bin/bash
PHP binary:	/usr/bin/php8.5
PHP version:	8.5.4
php.ini used:	/etc/php/8.5/cli/php.ini
MySQL binary:
MySQL version:
SQL modes:
WP-CLI root dir:	phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir:	phar://wp-cli.phar/vendor
WP_CLI phar path:	phar:///usr/local/bin/wp
WP-CLI packages dir:
WP-CLI cache dir:	/home/senthilkumar/.wp-cli/cache
WP-CLI global config:
WP-CLI project config:
WP-CLI version:	2.12.0

Para a documentação oficial de instalação, visite: https://wp-cli.org/#installing.

Métodos Alternativos de Instalação

O método PHAR acima funciona em todos os sistemas. No entanto, duas alternativas podem se adequar melhor ao seu fluxo de trabalho.

Ubuntu PPA (instalação com apt)

Se você gerencia servidores Ubuntu ou Debian e prefere instalar ferramentas através do apt, um PPA mantido pela comunidade-m fornece uma versão empacotada do WP-CLI:

sudo add-apt-repository ppa:tiagohillebrandt/wp-cli
sudo apt update
sudo apt install wp-cli

O PPA é mantido por um voluntário da comunidade e pode ficar ligeiramente atrás do último lançamento do WP-CLI. Para a versão mais recente, use o método PHAR acima. Verifique qual versão você tem com wp cli version após a instalação.

Instalação Global com Composer

Se você já usa o Composer em seu fluxo de trabalho de desenvolvimento PHP, pode instalar o WP-CLI como um pacote global do Composer:

composer global require wp-cli/wp-cli-bundle

Certifique-se de que o diretório bin global do Composer esteja em seu $PATH. Na maioria dos sistemas, é ~/.composer/vendor/bin ou ~/.config/composer/vendor/bin:

export PATH="$HOME/.composer/vendor/bin:$PATH"

Adicione essa linha ao seu ~/.bash_profile para torná-la permanente. Em seguida, confirme se o WP-CLI funciona:

wp --info

O método Composer é ideal se você quiser o WP-CLI fixado em uma versão específica em um projeto ou se sua equipe usar o Composer para gerenciamento de dependências entre ferramentas.

Instalação em Hospedagem Compartilhada

Alguns hosts compartilhados incluem o WP-CLI pré-instalado. Verifique a documentação do seu host ou execute wp --info diretamente após fazer login via SSH. Se retornar saída, o WP-CLI já está lá.

Se não estiver pré-instalado, mas seu plano incluir acesso SSH, você pode executar o arquivo PHAR diretamente sem movê-lo para um caminho global:

php wp-cli.phar --info

Para tornar isso um pouco mais fácil de digitar, adicione um alias ao seu ~/.bash_profile:

alias wp='php ~/wp-cli.phar'

Em seguida, recarregue o perfil:

source ~/.bash_profile

Depois disso, wp --info funciona como se estivesse instalado globalmente.

Habilitar Autocompletar com Tab

O WP-CLI suporta autocompletar com Tab no Bash, Zsh e Fish. Você pode baixar o script de autocompletar deste link: https://github.com/wp-cli/wp-cli/raw/main/utils/wp-completion.bash.

Para Bash, baixe o script de autocompletar e referencie-o a partir do ~/.bash_profile:

source /FULL/PATH/TO/wp-completion.bash

Em seguida, recarregue seu perfil:

source ~/.bash_profile

Para Zsh com Oh My Zsh, adicione wp-cli à sua linha de plugins no ~/.zshrc:

plugins=(wp-cli git ...)

Para Fish shell, baixe wp.fish e coloque-o em ~/.config/fish/completions/wp.fish. O Fish o referencia automaticamente quando você digita wp e pressiona Tab.

Perguntas Frequentes (FAQ)

P: Qual é a versão mínima do PHP para o WP-CLI? R: O WP-CLI requer PHP 7.2.24 ou posterior. A versão recomendada para 2026 é PHP 8.4. É mais rápido, ativamente suportado e a versão que a maioria dos hosts usa atualmente. Confirme a sua com php --version.

P: Instalei o PHP, mas o WP-CLI ainda lança um erro fatal sobre mysqli_init. O que está errado? R: O PHP está instalado, mas a extensão php-mysql está faltando. Instale-a com sudo apt install php-mysql (Ubuntu/Debian) ou sudo dnf install php-mysqlnd (RHEL/Fedora). Em seguida, confirme se foi carregada com php -m | grep mysqli.

P: Recebo o erro 2002 "No such file or directory" ao executar wp config create. Como corrigir? R: Substitua --dbhost=localhost por --dbhost=127.0.0.1. Isso força o PHP a usar uma conexão TCP em vez de um soquete Unix, o que corrige a incompatibilidade entre os caminhos do soquete PHP e MySQL em alguns sistemas.

P: Posso instalar o WP-CLI sem acesso sudo? R: Sim. Pule a etapa sudo mv e, em vez disso, execute o arquivo PHAR diretamente com php wp-cli.phar <command>, ou salve-o em um diretório no PATH do seu usuário, como ~/bin/wp, e adicione ~/bin ao seu $PATH.

P: Preciso reinstalar o WP-CLI quando atualizar o PHP? R: Não. O WP-CLI é um arquivo PHAR autocontido e não precisa ser reinstalado após uma atualização do PHP. No entanto, execute wp cli update periodicamente para manter o próprio WP-CLI atualizado.

P: Como atualizar o WP-CLI após instalá-lo? R: Execute este comando de qualquer lugar:

wp cli update

Verifique se há atualizações disponíveis primeiro sem aplicá-las:

wp cli check-update

Próximos Passos

O WP-CLI está instalado e verificado. Você está pronto para começar a executar comandos. Continue para a Parte 3 da série WP-CLI para aprender comandos essenciais do WP-CLI:

Esse guia cobre cada categoria de comando em detalhes - plugins, temas, usuários, bancos de dados, multisite, scripts de automação, integração CI/CD, comandos personalizados e melhores práticas de segurança. Ele também inclui uma folha de dicas completa que você pode marcar e consultar a qualquer momento.

Também nesta série: