Development

How to Make a WordPress Plugin Uninstall Cleanly

A WordPress plugin should clean up persistent data during uninstall according to a documented retention policy. Deactivation is for stopping runtime behavior, such as scheduled work; it should not normally erase user data.

The first design decision is what deletion means. A cache can usually be rebuilt. Customer records, membership history, and financial references may need to remain available after the plugin code is removed.

Define the plugin uninstall policy

List every persistent resource the plugin owns: options, transients, metadata, custom tables, scheduled hooks, uploaded files, and remote registrations. Record the exact names and whether each item is disposable, retained by default, or removable only through an explicit setting.

Do not use a broad prefix match as a substitute for this inventory. A similarly named option may belong to another plugin or to a previous integration that still needs it.

Show the retention setting before uninstall. Explain what will be removed and provide an export path where appropriate. The user should not discover the policy after the Delete button has already run it.

Use a guarded uninstall.php file

WordPress supports an uninstall.php file in the plugin root. Guard it with WP_UNINSTALL_PLUGIN so direct requests do not execute deletion logic. The official uninstall guide describes this entry point and its distinction from deactivation.

This example concerns a single-site plugin that owns two options, one transient, and one cron hook:

<?php

if (!defined('WP_UNINSTALL_PLUGIN')) {
    exit;
}

$retainData = get_option('ml_example_retain_data', 'yes') !== 'no';
wp_clear_scheduled_hook('ml_example_refresh');
delete_transient('ml_example_status');

if (!$retainData) {
    delete_option('ml_example_settings');
    delete_option('ml_example_retain_data');
}

Retention defaults to yes. Clearing scheduled work and disposable cached status is separate from deleting saved settings. This file deliberately does not load the plugin's normal bootstrap: uninstall should not depend on code that registers front-end behavior or contacts remote services.

If your cron events use arguments, clear the exact argument combinations you scheduled. A hook name alone does not necessarily identify every event variant. Keep a record of those combinations or use the documented cleanup API appropriate to the installed WordPress version.

Keep deactivation small

On deactivation, clear scheduled events and release temporary runtime registrations. Leave persistent content available for reactivation. Treat an upgrade that briefly deactivates code as distinct from an intentional permanent deletion.

For custom tables, drop only known plugin-owned tables when the user has explicitly selected removal. Build identifiers from the trusted WordPress database prefix and a fixed table suffix. Never concatenate a request parameter into DROP TABLE.

File deletion needs equally narrow ownership. Keep generated files in a dedicated directory and verify paths before removal. Do not recursively delete the general uploads directory or assume that every file referenced by a plugin record belongs exclusively to that plugin.

Handle multisite explicitly

The sample is single-site only. A network-enabled plugin may own per-site options and tables plus network options. Document which stores exist, then plan bounded cleanup across sites. A large network can exceed a synchronous uninstall request's time limit.

Test the actual network lifecycle, including a deleted site, a site added after activation, and a plugin that was activated on only part of the network. Do not copy a single-site loop into production and assume it scales indefinitely.

Remote subscriptions and API registrations need their own policy. Deleting a WordPress plugin should not silently cancel a paid service unless that behavior is explicit and authorized. Remote outages must not leave local deletion in an ambiguous half-finished state.

Verify clean removal

Create fixtures under both retention choices. Activate, save settings, schedule work, deactivate, reactivate, then uninstall. Confirm that retained data survives and removable data disappears without affecting unrelated options, files, or tables.

Also test a direct request to uninstall.php; it must not delete anything. Review legacy PHP changes without broad rewrites when cleanup touches an older plugin, or discuss a lifecycle review.