WP-CLIをインストールしてWordPressの未添付画像を完全削除する手順

WordPressサーバーにWP-CLIが入っていない場合でも、公式のPharファイルを導入すれば、コマンドラインからメディアを整理できます。本記事では、WP-CLIのインストール、動作確認、未添付画像の抽出、ドライラン、完全削除、ディスク容量の比較までを順番に説明します。

重要: WordPressで「未添付」と判定される画像は、データベース上の post_parent が0の添付ファイルです。本文、アイキャッチ、ウィジェット、CSS、テーマ設定、カスタムフィールドなどから参照されていても未添付と表示される場合があります。削除前に必ずバックアップと対象確認を行ってください。

前提条件
PHP CLIとcurlを確認する
1. Debian・Ubuntu系の例
2. RHEL・Rocky Linux・AlmaLinux系の例
WP-CLIの公式Pharを取得する
チェックサムを検証する
Pharファイル単体で動作確認する
WP-CLIをサーバーへインストールする
WordPressへの接続を確認する
作業前の容量を記録する
WordPressとデータベースをバックアップする
1. アップロードファイルをバックアップする例
2. データベースをWP-CLIでバックアップする例
未添付画像の件数を確認する
削除対象をCSVへ保存する
対象IDを固定して検証する
未添付画像を完全削除する
削除後の残件数を確認する
削除後の容量を確認する
管理画面に削除済み画像が表示される場合
1. WordPressオブジェクトキャッシュを削除する
2. APCuを使用している場合
作業ファイルを片付ける
WP-CLIを更新する方法
安全に作業するための注意点

前提条件

LinuxサーバーへSSH接続できること
WordPressの設置パスを把握していること
PHPのCLI版とcurlが利用できること
/usr/local/bin へファイルを配置できるsudo権限があること
WordPressファイルとデータベースをバックアップできること

この記事では、次の値をダミーとして使用します。実際の環境に合わせて置き換えてください。

WordPress設置パス: /var/www/example.com/public_html
Webサーバー実行ユーザー: www-data
WP-CLI設置先: /usr/local/bin/wp
作業ディレクトリ: /var/tmp/wp-cli-install
PHP-FPMサービス名: php8.3-fpm

PHP CLIとcurlを確認する

php -v
curl --version

コマンドが見つからない場合は、OSのパッケージ管理機能でPHP CLIとcurlをインストールします。パッケージ名はOSやPHPのバージョンによって異なります。

Debian・Ubuntu系の例

sudo apt update
sudo apt install php-cli curl

RHEL・Rocky Linux・AlmaLinux系の例

sudo dnf install php-cli curl

WP-CLIの公式Pharを取得する

作業用ディレクトリを作成し、WP-CLI公式のPharファイルとSHA-512チェックサムを取得します。

sudo install -d -m 0700 /var/tmp/wp-cli-install
cd /var/tmp/wp-cli-install

curl -fL -o wp-cli.phar \
  https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

curl -fL -o wp-cli.phar.sha512 \
  https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar.sha512

リダイレクトを許可するため -L、HTTPエラー時に失敗させるため -f を付けています。

チェックサムを検証する

expected="$(awk '{print $1}' wp-cli.phar.sha512)"
actual="$(sha512sum wp-cli.phar | awk '{print $1}')"

printf 'expected=%s\nactual=%s\n' "$expected" "$actual"
test "$expected" = "$actual"

test がエラーなく終了し、2つの値が一致していることを確認します。一致しない場合はインストールを中止し、取得元URL、ネットワーク、プロキシ、ダウンロード内容を確認してください。

Pharファイル単体で動作確認する

php wp-cli.phar --info

PHPのバージョン、WP-CLIのバージョン、Pharパスなどが表示されれば、Pharファイルは起動できます。

WP-CLIをサーバーへインストールする

chmod 0755 wp-cli.phar
sudo install -o root -g root -m 0755 \
  wp-cli.phar /usr/local/bin/wp

インストール後、PATHから実行できることを確認します。

command -v wp
wp --info
wp cli version

/usr/local/bin/wp が表示され、バージョン情報を取得できればインストール完了です。

WordPressへの接続を確認する

WordPressファイルの所有者やWebサーバー実行ユーザーに合わせて実行します。rootのまま実行せず、WordPressを操作する適切なユーザーを指定してください。

sudo -u www-data wp \
  --path=/var/www/example.com/public_html \
  --skip-themes --skip-plugins \
  core is-installed

sudo -u www-data wp \
  --path=/var/www/example.com/public_html \
  --skip-themes --skip-plugins \
  option get siteurl

sudo -u www-data wp \
  --path=/var/www/example.com/public_html \
  --skip-themes --skip-plugins \
  core version

core is-installed が成功し、サイトURLとWordPressバージョンが表示されることを確認します。

作業前の容量を記録する

df -B1 /var/www/example.com/public_html
du -sb /var/www/example.com/public_html/wp-content/uploads

df -h /var/www/example.com/public_html
du -sh /var/www/example.com/public_html/wp-content/uploads

削除後に同じコマンドを実行し、ファイルシステムの空き容量と uploads の使用量を比較します。

WordPressとデータベースをバックアップする

完全削除は元に戻せません。データベースと wp-content/uploads をバックアップしてください。

アップロードファイルをバックアップする例

sudo tar -C /var/www/example.com/public_html/wp-content \
  -czf /var/backups/example-uploads-YYYYMMDD-HHMMSS.tar.gz uploads

データベースをWP-CLIでバックアップする例

sudo -u www-data wp \
  --path=/var/www/example.com/public_html \
  --skip-themes --skip-plugins \
  db export /var/tmp/example-wordpress-YYYYMMDD-HHMMSS.sql

出力先へWebサーバー実行ユーザーが書き込めない場合は、事前に権限を調整するか、管理者用の安全なバックアップ方法を使用してください。バックアップファイルをWeb公開ディレクトリへ置かないでください。

未添付画像の件数を確認する

sudo -u www-data wp \
  --path=/var/www/example.com/public_html \
  --skip-themes --skip-plugins \
  post list \
  --post_type=attachment \
  --post_status=inherit \
  --post_parent=0 \
  --post_mime_type=image \
  --format=count

この段階では件数を表示するだけで、削除は行いません。

削除対象をCSVへ保存する

ID、タイトル、MIMEタイプ、登録日時をCSVへ保存し、削除前に内容を確認します。

sudo -u www-data wp \
  --path=/var/www/example.com/public_html \
  --skip-themes --skip-plugins \
  post list \
  --post_type=attachment \
  --post_status=inherit \
  --post_parent=0 \
  --post_mime_type=image \
  --fields=ID,post_title,post_mime_type,post_date \
  --format=csv \
  > /var/tmp/unattached-images-before-delete.csv

CSVの行数と内容を確認します。

wc -l /var/tmp/unattached-images-before-delete.csv
sed -n '1,30p' /var/tmp/unattached-images-before-delete.csv

CSVには見出し行が含まれるため、画像件数は通常「行数から1を引いた値」です。アイキャッチ、固定ページ、ウィジェット、テーマ設定、CSSなどで使われている画像が疑われる場合は削除を中止してください。

対象IDを固定して検証する

削除中に対象が変化しないよう、ID一覧をファイルへ保存します。作業中はメディアのアップロードや記事編集を停止してください。

sudo -u www-data wp \
  --path=/var/www/example.com/public_html \
  --skip-themes --skip-plugins \
  post list \
  --post_type=attachment \
  --post_status=inherit \
  --post_parent=0 \
  --post_mime_type=image \
  --format=ids \
  | tr ' ' '\n' \
  | sed '/^$/d' \
  > /var/tmp/unattached-image-ids.txt

ID以外の文字が混ざっていないことを確認します。

test -s /var/tmp/unattached-image-ids.txt
if grep -Evq '^[0-9]+$' /var/tmp/unattached-image-ids.txt; then
  echo 'ID validation failed' >&2
  exit 1
fi

wc -l /var/tmp/unattached-image-ids.txt
sed -n '1,30p' /var/tmp/unattached-image-ids.txt

未添付画像を完全削除する

バックアップ、CSV、ID一覧を確認したら、50件ずつ完全削除します。--force を指定するため、ゴミ箱を経由せず、関連サムネイルと投稿メタを含めて削除されます。

xargs -r -n 50 sudo -u www-data wp \
  --path=/var/www/example.com/public_html \
  --skip-themes --skip-plugins \
  post delete --force \
  < /var/tmp/unattached-image-ids.txt \
  | tee /var/tmp/unattached-images-delete.log

大量削除では時間がかかることがあります。SSH接続が切れても処理状態を確認できるよう、必要に応じてtmuxやscreen内で実行してください。

削除後の残件数を確認する

sudo -u www-data wp \
  --path=/var/www/example.com/public_html \
  --skip-themes --skip-plugins \
  post list \
  --post_type=attachment \
  --post_status=inherit \
  --post_parent=0 \
  --post_mime_type=image \
  --format=count

結果が 0 なら、WordPressデータベース上の未添付画像は残っていません。0でない場合は、削除ログのエラーを確認し、残ったIDを再取得して原因を調べます。

削除後の容量を確認する

df -B1 /var/www/example.com/public_html
du -sb /var/www/example.com/public_html/wp-content/uploads

df -h /var/www/example.com/public_html
du -sh /var/www/example.com/public_html/wp-content/uploads

削除前後の値から、空き容量の増加量と uploads の減少量を計算します。データベース更新やファイルシステムの割り当て単位により、両者は完全には一致しない場合があります。

管理画面に削除済み画像が表示される場合

削除後も管理画面の「メディア」に古い情報が表示される場合は、ブラウザの再読み込み、WordPressキャッシュ、オブジェクトキャッシュ、APCu、PHP-FPMのキャッシュを確認します。

WordPressオブジェクトキャッシュを削除する

sudo -u www-data wp \
  --path=/var/www/example.com/public_html \
  --skip-themes --skip-plugins \
  cache flush

キャッシュプラグイン、Redis、Memcachedを使用している場合は、各システムの管理手順に従います。共有キャッシュを一括削除すると、他サイトへ影響する可能性があります。

APCuを使用している場合

PHP CLIのAPCuとPHP-FPMのAPCuは別プロセスの場合があります。CLIからキャッシュを消しても管理画面側へ反映されないときは、影響範囲を確認して対象PHP-FPMサービスを再読み込みします。

sudo systemctl reload php8.3-fpm

サービス名は環境によって異なります。共有サーバーでは他サイトへの影響を確認してから実行してください。

作業ファイルを片付ける

バックアップを別の安全な場所へ保管したあと、不要な作業ファイルを削除します。

sudo rm -f /var/tmp/unattached-images-before-delete.csv
sudo rm -f /var/tmp/unattached-image-ids.txt
sudo rm -f /var/tmp/unattached-images-delete.log
sudo rm -rf /var/tmp/wp-cli-install

rm を実行する前に、対象パスが正しいことを必ず確認してください。

WP-CLIを更新する方法

WP-CLIは定期的に更新されます。更新前に現在のバージョンと更新内容を確認し、管理者権限で実行します。

wp cli version
sudo wp cli update
wp cli version

運用ポリシー上、自己更新を許可しないサーバーでは、初回と同様に公式Pharとチェックサムを取得して入れ替えます。

安全に作業するための注意点

WP-CLIのPharは公式配布元から取得し、チェックサムを検証する
WordPress操作をrootで実行しない
削除前にデータベースとuploadsをバックアップする
件数確認、CSV保存、ID検証を済ませてから削除する
最初から全メディアを対象にせず、画像・未添付に条件を限定する
削除中はメディアのアップロードや記事編集を停止する
キャッシュ削除やPHP-FPM再読み込みの影響範囲を確認する

WP-CLIを導入すると、未添付画像の件数確認、対象IDの保存、完全削除、残件確認を再現可能なコマンドで実行できます。大量のメディアを整理するときは、インストール元の検証、バックアップ、ドライラン相当の一覧保存、対象IDの固定、削除後の容量確認までを一連の手順として実施してください。