WordPressのユーザーメタを一括編集する方法｜WP-CLIとupdate_user_meta・CSVでの更新

WordPress のユーザー情報を、数百人・数千人分まとめて書き換えたいことがあります。たとえば、会員全員にニュースレター配信の印を付ける、古い項目名を新しい名前に移す、CSV の一覧に合わせて会社名を入れる、といった作業です。管理画面の「ユーザー」一覧では1人ずつしか編集できないため、WP-CLI か、WordPress の関数を使うスクリプトでまとめて更新します。この記事では、その手順と注意点を説明します（2026年10月時点の WordPress と WP-CLI の公式ドキュメントに基づきます）。

ユーザーの情報が入っている場所

ユーザーの情報は、2つのテーブルに分かれて保存されています。どちらに入っている項目かで、変え方が変わります。

メールアドレス（user_email）は wp_users の項目で、wp_usermeta にはありません。wp_usermeta に meta_key = 'user_email' の行を作っても、ログインやメール送信に使われるアドレスは変わりません。

テーブル名の wp_ は、wp-config.php の $table_prefix で決まる接頭辞です。サイトによっては wp123_ などになっているため、SQL を書くときは実際の名前を確かめます。

作業の前にバックアップを取る

一括更新は元に戻すのが大変です。最初にデータベースを保存しておきます。

# データベース全体を保存する
wp db export before-usermeta.sql

# ユーザーのテーブルだけを保存する場合（接頭辞が wp_ の例）
wp db export before-usermeta-users.sql --tables=wp_users,wp_usermeta

WP-CLI が使えない場合は、サーバー会社の管理画面のバックアップ機能や phpMyAdmin のエクスポートで保存します。本番サイトで初めて試すのではなく、ステージング環境やバックアップから作ったコピーで手順を確かめてから本番で実行します。

今の値を確かめる

更新する前に、どの項目名（メタキー）にどんな値が入っているかを確認します。

# ユーザー ID 12 のメタ情報をすべて表示する
wp user meta list 12

# 特定の項目だけを表示する
wp user meta get 12 company

プラグインが作った項目名は、プラグインの説明書やこの一覧で確認できます。wp_capabilities（権限グループ）や session_tokens のように WordPress 本体が使う項目は、メタとして直接書き換えず、後で説明する専用のコマンドを使います。

方法1: WP-CLI で1人ずつのコマンドを繰り返す

対象が数百人程度までなら、ユーザーの一覧を取り出して wp user meta update を繰り返すのが分かりやすい方法です。<user> には、ユーザー ID、ログイン名、メールアドレスのどれでも指定できます。

# 1人だけ更新する
wp user meta update 12 newsletter yes

# 購読者（subscriber）全員に newsletter = yes を設定する
for id in $(wp user list --role=subscriber --format=ids); do
  wp user meta update "$id" newsletter yes
done

wp user list --format=ids は、条件に合うユーザーの ID を空白区切りで出力します。--role のほか、WP_User_Query が受け付ける条件（例: --meta_key=… --meta_value=…）でも絞り込めます。

wp_users の項目や名前は、wp user update で変えます。複数の ID をまとめて指定できます。

# 複数のユーザーの名（first_name）を変える
wp user update 12 13 14 --first_name=未設定

# メールアドレスを変える（本人への変更通知メールを送らない）
wp user update 12 --user_email=new@example.com --skip-email

この方法は、コマンドを実行するたびに WordPress を読み込み直すため、数千人を超えると時間がかかります。その場合は次の方法2を使います。

方法2: update_user_meta() を使うスクリプトでまとめて更新する

ユーザーが多い場合や、今の値によって新しい値を決めたい場合は、PHP のスクリプトを書いて wp eval-file で実行します。WordPress の関数を通して更新するため、キャッシュの更新やフック（プラグインの処理）も通常どおり動きます。

次の例は、購読者全員の newsletter を yes にします。500人ずつ取り出してメモリの使いすぎを防ぎ、dry-run を付けて実行すると、書き換えずに変更内容だけを表示します。

<?php
// bulk-user-meta.php
// 実行: wp eval-file bulk-user-meta.php dry-run（確認だけ）
//       wp eval-file bulk-user-meta.php（実際に更新）
$meta_key  = 'newsletter';
$new_value = 'yes';
$dry_run   = in_array( 'dry-run', $args, true );
$per_page  = 500;
$paged     = 1;
$changed   = 0;

do {
	$user_ids = get_users( array(
		'role'    => 'subscriber',
		'fields'  => 'ID',
		'number'  => $per_page,
		'paged'   => $paged,
		'orderby' => 'ID',
	) );

	foreach ( $user_ids as $user_id ) {
		$old = get_user_meta( $user_id, $meta_key, true );
		if ( $old === $new_value ) {
			continue; // すでに同じ値なら何もしない
		}
		if ( $dry_run ) {
			WP_CLI::log( "{$user_id}: '{$old}' -> '{$new_value}'" );
		} else {
			update_user_meta( $user_id, $meta_key, $new_value );
		}
		$changed++;
	}

	$paged++;
} while ( count( $user_ids ) === $per_page );

WP_CLI::success( ( $dry_run ? '変更予定: ' : '更新: ' ) . $changed . ' 人' );

wp eval-file では、ファイル名の後ろに書いた値が $args という配列で渡されます。対象の絞り込みを、更新するメタキーそのもので行う場合（例: 「newsletter が空の人」）は、更新するにつれて対象が減り、ページ送りがずれて一部を飛ばすことがあります。その場合は、先に ID の一覧をすべて取り出してから更新します。

update_user_meta() は、新しく追加したときはメタの ID、既存の値を変えたときは true、失敗したときや値が同じだったときは false を返します。

方法3: CSV の一覧に合わせて更新する

担当者から受け取った一覧などに合わせて値を入れる場合は、CSV を読み込むスクリプトにします。次の例は、1行目が user_login,company の CSV を読み、ユーザーごとに company を更新します。

<?php
// update-from-csv.php
// 実行: wp eval-file update-from-csv.php users.csv
$file = $args[0] ?? '';
if ( ! is_readable( $file ) ) {
	WP_CLI::error( "CSV を読めません: {$file}" );
}

$fh      = fopen( $file, 'r' );
$header  = fgetcsv( $fh, null, ',', '"', '' );
$updated = 0;

while ( ( $row = fgetcsv( $fh, null, ',', '"', '' ) ) !== false ) {
	if ( count( $row ) !== count( $header ) ) {
		WP_CLI::warning( '列の数が合わない行を飛ばしました: ' . implode( ',', $row ) );
		continue;
	}
	$data = array_combine( $header, $row );
	$user = get_user_by( 'login', $data['user_login'] );
	if ( ! $user ) {
		WP_CLI::warning( "ユーザーが見つかりません: {$data['user_login']}" );
		continue;
	}
	update_user_meta( $user->ID, 'company', sanitize_text_field( $data['company'] ) );
	$updated++;
}
fclose( $fh );

WP_CLI::success( "{$updated} 人を更新しました" );

CSV は UTF-8 で保存します。Excel で作った CSV は Shift_JIS になっていることがあり、そのままだと日本語が文字化けします。Excel では「CSV UTF-8（コンマ区切り）」の形式で保存してください。

権限グループと不要な項目の扱い

権限グループは wp_capabilities というメタに入っていますが、直接書き換えず、WP-CLI のコマンドで変えます。

# 権限グループを置き換える
wp user set-role 12 editor

# 権限グループを追加する
wp user add-role 12 author

使わなくなった項目は、wp user meta delete で消せます。全ユーザーから同じ項目を消す場合は、方法1と同じように ID の一覧で繰り返すか、スクリプトで delete_metadata( 'user', 0, 'old_key', '', true ); を実行します（最後の true で全ユーザーが対象になります）。

wp user meta delete 12 old_key

SQL で直接書き換える場合の注意

WP-CLI もスクリプトも使えず、phpMyAdmin などで SQL を実行するしかない場合は、次の点に注意します。

• 接頭辞を確かめる: テーブル名は $table_prefix で変わります。
• シリアライズされた値は書き換えない: a:2:{…} のような値は文字数が埋め込まれているため、REPLACE() で文字を置き換えると壊れて読めなくなります。
• キャッシュを消す: Redis などの永続オブジェクトキャッシュを使っていると、SQL で変えた値が反映されないことがあります。更新後に wp cache flush やキャッシュプラグインの消去を行います。
• プラグインの処理は動かない: WordPress の関数を通さないため、更新時に動くはずのフックは実行されません。

-- 更新前に対象を確認する
SELECT user_id, meta_value FROM wp_usermeta WHERE meta_key = 'newsletter';

-- 単純な文字列の値だけを変える
UPDATE wp_usermeta SET meta_value = 'yes' WHERE meta_key = 'newsletter' AND meta_value = 'no';

UPDATE は、その項目を持っているユーザーの行だけを書き換えます。項目をまだ持っていないユーザーには行が無いため、値は追加されません。全員に値を入れたいなら、方法1か方法2を使います。

更新後に確かめる

# 値ごとの人数を数える
wp user list --role=subscriber --meta_key=newsletter --meta_value=yes --format=count

# 何人かを選んで中身を見る
wp user meta get 12 newsletter

管理画面でも数人のプロフィールを開き、値が表示や動作に反映されているかを確かめます。問題があれば、最初に取ったバックアップを wp db import before-usermeta.sql で戻します。

まとめ

• メールアドレスや表示名は wp_users、名前やプラグインの項目は wp_usermeta に入っている。項目の場所に合わせて wp user update と wp user meta update を使い分ける
• 作業の前に wp db export でバックアップを取り、ステージングで試してから本番で実行する
• 数百人程度なら WP-CLI の繰り返し、多い場合や条件付きなら update_user_meta() を使うスクリプトを wp eval-file で実行する
• 権限グループは wp user set-role で変え、メタを直接書き換えない
• SQL で直接変えるなら、接頭辞・シリアライズされた値・キャッシュに注意する

関連記事:

• WP-CLIでユーザーを管理するコマンド
• WP-CLIでカスタムフィールドを一括更新する
• WP-CLIのデータベース操作コマンド