Uninstall and cleanup hooks in Wordpress

Introduction

Uninstall and cleanup hooks help remove plugin data when you delete the plugin. This keeps your website clean and fast.

You want to delete plugin settings when the plugin is removed.

You want to clear custom database tables created by your plugin.

You want to remove options or user meta added by your plugin.

You want to avoid leaving unused data that slows down your site.

You want to keep your WordPress site tidy after uninstalling plugins.

Syntax

Wordpress

<?php
register_uninstall_hook(__FILE__, 'my_plugin_uninstall');

function my_plugin_uninstall() {
    // Cleanup code here
    delete_option('my_plugin_option');
    // Remove custom tables or meta
}
?>

The register_uninstall_hook function links your cleanup function to plugin uninstall.

The cleanup function should delete all plugin data like options, tables, or metadata.

Examples

This example deletes a normal option and a network-wide option on uninstall.

Wordpress

<?php
register_uninstall_hook(__FILE__, 'cleanup_plugin_data');

function cleanup_plugin_data() {
    delete_option('plugin_setting');
    delete_site_option('plugin_network_setting');
}

This example deletes a custom database table created by the plugin.

Wordpress

<?php
register_uninstall_hook(__FILE__, 'remove_custom_table');

function remove_custom_table() {
    global $wpdb;
    $table = $wpdb->prefix . 'custom_table';
    $wpdb->query("DROP TABLE IF EXISTS $table");
}

This example removes user meta data added by the plugin.

Wordpress

<?php
register_uninstall_hook(__FILE__, 'delete_user_meta_data');

function delete_user_meta_data() {
    global $wpdb;
    $wpdb->query("DELETE FROM $wpdb->usermeta WHERE meta_key = 'plugin_user_meta'");
}

Sample Program

This plugin creates an option and a custom table on activation. When uninstalled, it deletes the option, drops the table, and removes user meta data related to the plugin.

Wordpress

<?php
/**
 * Plugin Name: Cleanup Example
 */

register_uninstall_hook(__FILE__, 'cleanup_example_uninstall');

function cleanup_example_uninstall() {
    // Remove plugin option
    delete_option('cleanup_example_option');

    // Remove custom table
    global $wpdb;
    $table_name = $wpdb->prefix . 'cleanup_example_table';
    $wpdb->query("DROP TABLE IF EXISTS $table_name");

    // Remove user meta
    $wpdb->query("DELETE FROM $wpdb->usermeta WHERE meta_key = 'cleanup_example_user_meta'");
}

// Plugin activation creates option and table for demonstration
register_activation_hook(__FILE__, 'cleanup_example_activate');
function cleanup_example_activate() {
    add_option('cleanup_example_option', 'some value');
    global $wpdb;
    $table_name = $wpdb->prefix . 'cleanup_example_table';
    $charset_collate = $wpdb->get_charset_collate();
    $sql = "CREATE TABLE $table_name (
        id mediumint(9) NOT NULL AUTO_INCREMENT,
        data text NOT NULL,
        PRIMARY KEY  (id)
    ) $charset_collate;";
    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
    dbDelta($sql);
}

Important Notes

Uninstall hooks only run when the plugin is deleted from the WordPress admin, not when deactivated.

Always test uninstall code on a backup site to avoid accidental data loss.

Use register_uninstall_hook or an uninstall.php file for cleanup.

Summary

Uninstall hooks help remove all plugin data when deleting the plugin.

Use register_uninstall_hook to link a cleanup function.

Cleanup includes deleting options, custom tables, and user meta.