today while looking inside WP Codex, I saw two ways to handle plugin uninstall scripts (like deletings, options, data, tables etc.). One way is using register_uninstall_hook() and the other is by using the simple uninstall.php.

Though the codex page gives a lot of info about both of them, but it doesn't say what is the advantage of using one over another.

As there are so many WP gurus here, I thought I should ask this question about which option is the better way of handling uninstall script? Using register_uninstall_hook() or uninstall.php?

Hope somebody will clarify. Thanks in advance.


The benefit of uninstall.php, and the reason that it was introduced, is that it allows you to isolate your uninstallation code from the rest of your plugin's code. This means that your entire plugin doesn't have to be loaded when it is uninstalled. That minimizes the chance that your plugin will inadvertently run code during uninstallation that is only intended to be run when the plugin is active. However, in general, you shouldn't be running arbitrary code in your plugin files anyway, most everything should only run if triggered by a hook.

From the docs included in the original commit:

The plugin should not run arbitrary code outside of functions, when registering the uninstall hook. In order to run using the hook, the plugin will have to be included, which means that any code laying outside of a function will be run during the uninstall process. The plugin should not hinder the uninstall process.

If the plugin can not be written without running code within the plugin, then the plugin should create a file named 'uninstall.php' in the base plugin folder...

TL;DR: Your plugin should really be structured in such a way that it doesn't have to use unisntall.php, but using it anyway adds extra protection against accidentally running things during uninstall.

Of course, in some cases you may need to load parts of your plugin in order to uninstall it properly anyway. But if you are using uninstall.php, including those files will be a conscious decision that you make, so it is harder to mistakenly load some file of your plugin that runs arbitrary code.

The only time that I would use the register_uninstall_hook() method would be in a very simple, single-file plugin, where all of the code was encapsulated into a single class.

Note that uninstall_plugin() will run the pre_uninstall_plugin and uninstall_{$plugin_file} [edit: uninstall_{$plugin_file} will only run if register_uninstall_hook() is used] action hook regardless of which method you use. (See ticket #34569.)

  • Awesome answer. Actually I'm working on a new plugin where I've to create options and insert data within wp tables. So, it's my responsibility to clean up the database upon uninstall. So I was thinking which path should I take to run the unregister_settings, delete_option etc. Should I take the uninstall hook way or the uninstall file way. But after reading your answer, I think uninstall file way would be a good option. What do you think?
    – iSaumya
    Oct 8 '16 at 21:48
  • 1
    @iSaumya Yes, I'd use the uninstall file way, if it were me. The uninstall hook way might be a good fit for very simple single-file plugins where all of the code is encapsulated in a single class. In any other case I'd use the uninstall.php file.
    – J.D.
    Oct 9 '16 at 12:17
  • 1
    @iSaumya I just realized that I was actually wrong about the uninstall_{$plugin_file} hook running for both cases. @the_dramatist is correct that it only runs when register_uninstall_hook() is used. However, note that anything wishing to hook into plugin uninstall should probably be using pre_uninstall_plugin instead (which does indeed run for both). See ticket #34569. So I wouldn't make that a deciding factor in which of these you choose to use.
    – J.D.
    Oct 9 '16 at 12:29

Well, it depends on what you want. register_uninstall_hook() creates hooks and it executes when the uninstall link clicked. That means it actually create a hook which will be called on clicking the uninstall link. Say you developed a plugin and based on that plugin you want to create other plugins and those add on plugins needs to perform operation on based plugin uninstall, then this hook is gonna be useful. Here you'll get a full overview.

And uninstall.php is a generic uninstaller for your plugin. It'll fire upon your plugin uninstall. But it does not provide any hook by default.

Look here for further information.

  • 2
    You can put hooks into your uninstall.php too though. The link is the same as in the question. Any reference for your best practice? Oct 8 '16 at 16:22
  • 1
    Yea. We can put hooks in uninstall.php. But I said it's not provided by default. And for references please have a look on WordPress Plugin Development Boilerplate or any boilerplates. Here is the Tom McFarlin's boilerplate link github.com/DevinVinson/WordPress-Plugin-Boilerplate. And if you want to provide hooks through uninstall.php, you can do it. But as the context of his question I preferred the register_uninstall_hook().
    – CodeMascot
    Oct 8 '16 at 16:26
  • 1
    @the_dramatist It is not possible to provide both of these, see the source of uninstall_plugin(). The uninstall.php file will take precedence, and any uninstall hook will be ignored and the uninstall_{$plugin_file} action will not be fired.
    – J.D.
    Oct 9 '16 at 13:06

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.