I uploaded a plugin to the WordPress.org repository and some people enjoy the plugin. I use plugin.php as the base name for my plugin.

Every time I change something, I would like to change the name of the main file to the name of the plugin. But if I would do that I think that the users would get the error "plugin disabled because it could not be found".

Is there a way to specify the new base name for a plugin so that I can rename my main php file?

  • I would strongly advise against doing this, the only way I can think of would be extremely fragile and fail for anybody who updates past that particular version. As a personal aside, plugin.php is preferable as it's unambiguous, whereas the name of the plugin might be the main file, or it might be a class of that name, or it might be something else, etc
    – Tom J Nowell
    Commented Feb 7, 2022 at 17:27

2 Answers 2


There is no safe reliable way to do this, wether it is or is not on wordpress.org, and .org may get upset if you do this. You might also break automations on .org and on your customers sites.

Is there a way to specify the new base name for a plugin so that I can rename my main php file?

No there is no mechanism for this.

There is an ultra hacky workaround that will p*ss off all your users, break lots of things, but do the job for a minority of users who update regularly and are lucky.

The only "way" to do it would be to introduce a version of the plugin that has 2 main plugin files, and a filter to transfer from one to the other.


  • users will see 2 plugins listed when on this version
  • users who don't update to this version or update to the next version will not be migrated
  • security plugins may see this as an attack
  • users may then reactivate the old plugin
  • any filters users have made to auto-activate the plugin will be crippled, you will have broken their website
  • any users who put your plugin in a non-standard place then include it with an include or require will have their sites broken
  • the built in updater may upgrade the old plugin file to the newer version that has only your new basefile, get confused, and deactivate the plugin, or rollback the update assuming it had failed
  • in theory your new base file is actually a brand new plugin, there may be consequences in terms of your plugins listing and how the WP updater handles it

The cost to doing this is extremely high, with a minimal chance of success, all to satisfy a personal preference. Expect lots of upset users and support burden.

  • ok, I think I will stick with plugin.php =) Thanks anyway. Very interesting read!
    – Marc
    Commented Feb 7, 2022 at 20:46

It's a hacky task but I think it's a good one...

It's in the WP.org plugin guidelines to have the directory with the same name of the main plugin file.

Why? Because autoloading of translation (from WP4.7) is based on text-domain which need to be also the same.

You should contact plugin reviewer team at [email protected] to know if they have any guidelines for you.

  • you can set the textdomain in the plugin header and there's a filter in the docs for adjusting this if it differs or you want to load it from a different place
    – Tom J Nowell
    Commented Feb 7, 2022 at 23:46
  • Yes, but... if the plugin is in the WordPress repository, then the translation is done at translate.wordpress.org and from WP 4.6, if all is matching, there's no need to use load_plugin_textdomain() Commented Feb 8, 2022 at 6:12

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.