Cleaning Up Old WordPress Revisions with WP-CLI

What WordPress Revisions Are and Why You Should Delete Them

A revision is a saved previous version of a post, page, or another content type for which revision support is enabled. It allows you to review changes and restore text if an editor accidentally deletes part of the content.

Revisions are stored as separate entries in the wp_posts table. Depending on the theme, plugins, and content type, related metadata may also be associated with them. The table name may differ if WordPress was installed with a different table prefix.

Deleting old revisions does not delete published posts, pages, or current versions of content. However, after cleanup, editors will no longer be able to restore the specific previous versions that were deleted.

• the size of the database and backups is reduced;
• fewer unnecessary entries remain in the database;
• there are fewer old versions to process during site maintenance.

Check the Site and Prepare a Backup

Before cleanup, make sure WP-CLI is running from the root directory of the intended WordPress site. You can check this with the wp core is-installed command. If the server hosts multiple sites, add the --path parameter or run the commands from the correct directory.

For a production site, create a database backup first. For example, WP-CLI can export the database to an SQL file. Make sure the file was actually created, has a non-zero size, and is available for restoration. If possible, test importing the backup in a staging environment.

If the site runs in Multisite mode, verify which site and which tables the command will process. Do not run cleanup with an incorrect --url or --path parameter.

• perform the cleanup on a staging copy first;
• check available disk space before creating the dump;
• store the backup separately from the server hosting the site;
• do not run the command during critical editor changes or a migration.

wp core is-installed
wp db export wordpress-before-revisions-cleanup.sql

How to Count and Inspect Revisions

First, determine the total number of entries with the revision post type. The most compatible approach is to retrieve the IDs and count them in the shell. If your version of WP-CLI supports the count format, you can use the shorter command.

It is also useful to view several of the first results with their date, parent post, and title. This helps confirm that the command is working with the intended site rather than another WordPress installation.

• a large number of revisions does not necessarily indicate a problem—it depends on how frequently content is edited;
• check whether editors use revisions as part of their workflow;
• pay attention to editorial, translation, or content-approval plugins that may also work with versions.

wp post list --post_type=revision --format=ids | wc -w
wp post list --post_type=revision --format=count
wp post list --post_type=revision --fields=ID,post_parent,post_date,post_title --format=table --number=20

Delete Old Revisions in Batches with WP-CLI

For cleanup, use wp post delete with the --force parameter. It deletes revisions without moving them to the Trash. For revisions, this is generally necessary because moving them to the Trash temporarily provides little practical benefit but may create additional entries.

Passing all IDs as one large list is not recommended because the shell may exceed the command-line length limit. Therefore, pass the IDs in batches, for example, 100 values at a time.

The -r option for xargs is available in GNU environments, which are commonly used on Linux. On some BSD systems, including macOS, the -r option may be unavailable. In that case, check man xargs or use an equivalent script that does not run the command for an empty list.

• do not delete entries with a direct SQL query unless you understand the related data and WordPress hooks;
• for the first run, use a small test batch and verify the result;
• do not interrupt the process unnecessarily if editors are working on the site at the same time.

wp post list --post_type=revision --format=ids \
| xargs -r -n 100 wp post delete --force

How to Perform a Test Cleanup

If you want to test the command's behavior first, retrieve a limited number of IDs and delete only those. Then open several related posts in the editor and make sure the published content remains unchanged.

After the test, count the revisions again. The number should decrease by approximately the number of deleted entries if no one created new versions in the meantime.

wp post list --post_type=revision --format=ids --number=10 \
| xargs -r -n 10 wp post delete --force

What to Check After Cleanup

When the command finishes, count the revisions again and make sure WP-CLI did not report access, database connection, or individual entry errors. Then check several posts on the site and in the administration area.

It is especially important to test the editor, saving changes, previewing, and restoring an available revision. If the site has custom post types, also check their pages and related functionality.

Deleting entries does not always immediately reduce the database file size on disk. This depends on the database management system, table structure, and subsequent maintenance. Do not treat the absence of an immediate reduction in the dump file size as evidence that deletion failed.

• check the revision count with the command again;
• open several posts and pages on the front end;
• test saving a change;
• review WP-CLI and PHP logs if the command ended with an error;
• if necessary, plan table optimization separately after creating a backup.

wp post list --post_type=revision --format=count
wp post list --post_type=revision --format=ids | wc -w

How to Limit the Accumulation of New Revisions

Cleanup removes revisions that already exist but does not change WordPress's future behavior. To store no more than a few of the latest versions for each post, add the WP_POST_REVISIONS constant to wp-config.php. A value of 5 limits the number of revisions for an individual post.

Place the line before the comment indicating the end of wp-config.php editing. After making the change, verify that the file contains no syntax errors and that the site and editor open correctly.

Do not set the value to 0 solely to stop database growth. This setting may effectively prevent editors from restoring previous versions. If revisions are needed, it is better to set a small positive number. This setting also does not delete entries that have already accumulated; they must be cleaned up separately.

• agree on the limit with editors and consider content restoration requirements;
• keep several versions for important content;
• remember that individual plugins may have their own history-retention logic.

define('WP_POST_REVISIONS', 5);

Common Mistakes When Cleaning Up Revisions

The most common problem is running the command from the wrong directory or against the wrong site. On a server with multiple installations, always check the path, URL, and number of revisions found before deletion.

The second mistake is not having a backup. Even if the command is intended to delete only entries with the revision post type, an incorrect parameter or third-party code can have unforeseen consequences.

Do not clean up revisions during active editing, immediately after updating a complex plugin, or without checking compatibility with a content-approval system. For large sites, it is better to run the process during a period of low activity and monitor the execution log.

• do not confuse revisions with published posts;
• do not use one large list of IDs without batching;
• do not delete data directly with SQL unless all dependencies have been checked;
• do not treat WP_POST_REVISIONS as a replacement for backups;
• do not run the command with --allow-root without a real need and a clear understanding of the consequences.