{"id":20875,"date":"2026-10-12T10:21:00","date_gmt":"2026-10-12T08:21:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=20875"},"modified":"2026-10-09T22:46:42","modified_gmt":"2026-10-09T20:46:42","slug":"plugin-lifecycle-uninstall","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/wordpress-plugins-tricks\/plugin-lifecycle-uninstall\/","title":{"rendered":"Activation, deactivation, uninstall: the plugin lifecycle"},"content":{"rendered":"

Many plugins leave traces long after they have stopped doing useful work: a table nobody reads, cron events with no callback left to handle them, or a capability on the administrator role that no longer controls access to any screen. WordPress offers three separate entry points for activation, deactivation and uninstall, with some behaviour that is easy to overlook. The activation hook does not run on updates, a network activation on multisite fires exactly once instead of once per site, and an uninstall routine registered as a closure ends in a fatal error.<\/p>\n

This article follows a small but complete plugin through all three phases. It creates its own table with dbDelta()<\/code>, stores a schema version and migrates on updates, schedules a daily cron event, grants a capability to administrators and removes all of it again through an uninstall.php<\/code> that deletes data only after an explicit opt-in. Every statement about core behaviour is checked against the handbook, the function reference and the source code of WordPress 7.1.2, the current release on 29.09.2026.<\/p>\n

Three phases, three entry points<\/h2>\n

The Plugin Handbook separates the phases cleanly: activation is the place for rewrite rules, custom tables and default options, deactivation removes temporary data such as caches, and only uninstall should remove permanent data like options and tables.<\/p>\n

Technically, register_activation_hook()<\/code> and register_deactivation_hook()<\/code> are thin wrappers. Both call plugin_basename()<\/code> on the file passed in and attach the callback to a dynamic action, activate_{$plugin}<\/code> or deactivate_{$plugin}<\/code>. The first argument therefore has to be the main plugin file, normally __FILE__<\/code> in that very file. Uninstall works differently: either WordPress includes an uninstall.php<\/code> from the plugin folder, or it calls a callback registered with register_uninstall_hook()<\/code>. Both variants run only when the plugin is deleted, not when it is deactivated.<\/p>\n\n\n\n\n\n\n\n\n
Phase<\/th>\nEntry point<\/th>\nExample plugin: creates or removes<\/th>\n<\/tr>\n<\/thead>\n
Activation<\/td>\nregister_activation_hook()<\/code><\/td>\ncreates table, schema version, capability, cron event<\/td>\n<\/tr>\n
Update<\/td>\nno hook, version check on plugins_loaded<\/code><\/td>\nsame setup routine, plus data migration<\/td>\n<\/tr>\n
Deactivation<\/td>\nregister_deactivation_hook()<\/code><\/td>\nremoves cron event and transient, keeps everything else<\/td>\n<\/tr>\n
Uninstall<\/td>\nuninstall.php<\/code><\/td>\nalways removes capability, cron and cache; table, options and user meta only after opt-in<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\n\"Plugin
Example plugin LW Search Log: activation sets up, deactivation stops, uninstall deletes data only after opt-in<\/figcaption><\/figure>\n

Activation is not an update hook<\/h2>\n

Since WordPress 3.1 the activation hook no longer fires on updates. Andrew Nacin explained the change on Make WordPress Core in October 2010: before that, the hook ran on single updates but not on bulk updates, and manual updates via FTP or SVN never triggered it. The recommendation from the same post still applies: a version is stored in the database and compared with the version in the code, and the upgrade procedure runs whenever the two differ.<\/p>\n

The current source confirms this. Before an update, Plugin_Upgrader::deactivate_plugin_before_upgrade()<\/code> deactivates an active plugin with deactivate_plugins( $plugin, true )<\/code>, and the second argument means silent, so no deactivation hook runs. During background updates via cron the plugin is not deactivated at all. Afterwards, wp-admin\/update.php<\/code> reactivates the plugin with activate_plugin( $plugin, '', ! empty( $_GET['networkwide'] ), true )<\/code>, again silently. The docblock of activate_plugin()<\/code> confirms that silent activation skips the activation hooks.<\/p>\n

The hook upgrader_process_complete<\/code> is a poor fit for migrations. It fires in the request that performed the update, and a note in the hook reference points out that the code running at that moment is still the old version of the plugin. A migration written for version 2 would therefore only run one update later. The version check on plugins_loaded<\/code>, as recommended by the handbook chapter on custom tables, runs on every request with the new code, no matter how the update arrived.<\/p>\n

Custom table with dbDelta and a versioned schema<\/h2>\n

Whether a separate table is worth it is covered in the article on the performance limits of wp_postmeta<\/a>; here it is a given. dbDelta()<\/code> lives in wp-admin\/includes\/upgrade.php<\/code>, which has to be included explicitly. The function compares a CREATE TABLE<\/code> statement with the existing table and adds what is missing. It parses the SQL as text and is strict about formatting. According to the handbook:<\/p>\n