I have inherited a plugin. If the plugin is called example and is in /wp-content/plugins/example what are the implications if the main plugin file is called example-plugin.php and not just example.php?

I know that the plugin will work, but are there any unforeseen problems that could arise?

I do understand that changing it will cause the plugin to deactivate, but there is a very clear notice.

FWIW this has come about because I am trying to use the internal updater on a custom Pro version of a plugin (that isn't in the repository) using this: getbutterfly.com/custom-wordpress-plugin-update-server and it only works if the plugin file name matches the plugin slug

  • 2
    I have never encountered such problems, so I don't know either. Also, Hello Dolly used a name that's different from the plugin slug (which should match the Plugin Name header, e.g. my-plugin if the header's value is My Plugin). But we should follow the plugin handbook's recommendation - "it’s also good to name this file after your plugin".
    – Sally CJ
    Commented Sep 25, 2023 at 0:52
  • 2
    "it only works if the plugin file name matches the plugin slug" - that is actually a plugin-specific requirement. What the plugin handbook stated, was simply a recommendation and not a requirement. So perhaps the plugin author was encouraging developers to follow the handbook's recommendation, but you'll need to consult them for the exact reasons why did they make that requirement.
    – Sally CJ
    Commented Sep 26, 2023 at 2:43
  • @SallyCJ this requirement was actually for the code I want to use for having my custom plugin updated by the native wordpress process. It isn't for the plugin itself.
    – Steve
    Commented Sep 27, 2023 at 10:01
  • 1
    I was saying that you could actually modify the custom updater plugin so that the plugin being checked doesn't need to have its main file's name be matching the plugin slug. ( basically, by changing all the $plugin_slug . '/' . $plugin_slug . '.php' to $plugin_slug . '/example-plugin.php' ) I already tried & tested that with WordPress v6.3.1, and my (test) plugin was updated just fine with the help of that custom updater plugin/code.
    – Sally CJ
    Commented Sep 27, 2023 at 16:24
  • Thanks @SallyCJ - I was considering that, but I have been under the pump with a flaky server. The original question was really an "out of curiosity" thing. :o)
    – Steve
    Commented Sep 27, 2023 at 23:08

1 Answer 1


It's only a good pratice to adopt this naming convention. As long as you have in the header of your main file the meta (at last Plugin name: Name of Your Plugin, WordPress will automatically recognize this file for being the main one.

Be aware that at the top of this file you should write at least :

 * Plugin Name: YOUR PLUGIN NAME

In the plugin handbook, WordPress it is written :

Create a new PHP file (it’s also good to name this file after your plugin, e.g. plugin-name.php).

[…] Only one file in the plugin’s folder should have the header comment — if the plugin has multiple PHP files, only one of those files should have the header comment.

As you can see, it's only a naming convention. It is not mandatory.

  • Thanks for that. Unfortunately it does affect the operation of the updater I am trying to get going, that requires that the main plugin file be named the same as the plugin slug.
    – Steve
    Commented Sep 25, 2023 at 23:11

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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