Plugin activation and deactivation hooks let you run code when a plugin is activated or deactivated. These hooks are essential for tasks that should happen only once — creating database tables, setting default options, flushing rewrite rules, or scheduling cron events. Proper use of these hooks ensures your plugin installs and uninstalls cleanly.
This guide covers how to use WordPress activation and deactivation hooks correctly.
Activation Hook
The activation hook runs when a user activates your plugin. Use register_activation_hook() in your main plugin file. The callback function handles setup tasks: setting default options with add_option(), creating custom database tables, scheduling recurring cron events with wp_schedule_event(), and flushing rewrite rules with flush_rewrite_rules().
Activation hooks run when the plugin is activated, not when it’s loaded. Code in the activation hook won’t run on every page load — only during activation.
Deactivation Hook
The deactivation hook runs when a user deactivates your plugin. Use register_deactivation_hook() to handle cleanup: clearing scheduled cron events with wp_clear_scheduled_hook(), flushing rewrite rules to remove your plugin’s rules, and cleaning up temporary data.
Deactivation hooks are for cleanup that should be reversed when the plugin is reactivated. Don’t delete permanent data like options or database tables during deactivation — users sometimes deactivate to troubleshoot and want their settings preserved.
Database Table Creation
Create custom database tables during plugin activation. Use dbDelta() from WordPress’s upgrade.php for table creation. dbDelta() compares the existing table structure with the desired structure and makes only necessary changes, making it safe to run on every activation.
Include the upgrade.php file before calling dbDelta(). Define the complete table schema in SQL. Use the $wpdb->prefix variable to support custom table prefixes.
Version Checking
Store your plugin’s database version in an option. During activation or on plugin load, compare the stored version with the current version. If they differ, run upgrade routines. This pattern lets you make database changes between versions without requiring users to manually run updates.
Use update_option() to store the version number. On each plugin load, check the version and run upgrade routines as needed.
Uninstall Hook
The uninstall hook runs when a user deletes your plugin through the WordPress admin. Use register_uninstall_hook() or create an uninstall.php file in your plugin’s root directory. The uninstall hook should delete all data created by your plugin — options, database tables, scheduled cron events, and custom files.
Uninstall.php is the recommended approach. WordPress automatically looks for this file when a plugin is deleted. If it exists, the uninstall.php code runs without needing a hook registration.
The Bottom Line
Activation, deactivation, and uninstall hooks handle the lifecycle of your plugin. Use activation for setup tasks, deactivation for reversible cleanup, and uninstall for permanent data deletion. Store a version number for upgrade routines. These hooks ensure your plugin installs cleanly, upgrades safely, and removes completely when no longer needed.
