Beginner's Guide for WordPress - Start your WordPress Blog in minutes.
Choosing the Best
WordPress Hosting
How to Easily
Install WordPress
WordPress Plugins
View all Guides

What, Why, and How-To’s of Creating a Site-Specific WordPress Plugin

Last updated on by
Follow WPBeginner on YouTube
What, Why, and How-To’s of Creating a Site-Specific WordPress Plugin

While creating the WPBeginner re-design, we saw a huge mistake that we made in our old site. All of our extra functionality that we added overtime was added in our old theme’s functions.php file. This not only caused our functions.php file to be super bloated, but it also increased the chance of error every time we modified that file. It was then we decided to take the advice of @otto42 and created a site-specific plugin. So you are probably wondering what a site-specific plugin is, why you need it, and how you can have it for your WordPress site. That is exactly what we plan to share in this article, so keep on reading.

What is a Site-Specific Plugin

Site-Specific WordPress plugin is a specific place to add snippets that you find on the web that performs functions that are not theme related. In other words:

Time to time again, you will read “how-to” articles related to WordPress all around the web (including our site) where we share snippets and suggest that you add them into your theme’s functions.php file. These snippets are not huge enough to be justified as plugins of their own, but some of them are certainly great to add specific functionality to a site that is not theme-dependent such as redirecting users to random post. Whereas other functions can be key to your specific site such as Custom Post Types.

This is when you need to add a site-specific plugin which essentially will serve as the same purpose of your theme’s functions.php file, but it will allow you to retain all these functionality when you are changing themes (see our checklist of things to do when changing WordPress themes).

Why You need a Site-Specfic Plugin for WordPress

As we mentioned above, it will allow you to retain all key additions to your site that you may have done overtime. Some functions that belong in a site specific plugin would be Custom Post Types, Adding Shortcodes, Adding WordPress Thumbnail Support, Redirecting users to a Random Post, and other independent functions that does not rely on your theme.

Above functions are something that you will need whether you change your theme or not. Can you imagine disabling a theme and then losing all of your shortocdes? That would be a total nightmare.

One of the reasons why we pasted beginner’s guide to pasting snippets from the web in WordPress was to prevent white screen of death that users get when pasting the snippet with wrong formatting. Often new users simply edit themes using the WordPress back-end to prevent the user of FTP. We have helped countless users who got locked out of their site when they pasted the wrong snippet.

When you use a site-specific plugin, you somewhat have a break-proof site. When you paste a snippet with wrong formatting, instead of the white screen of death the built-in plugin editor will recognize the error, and it will deactivate the plugin. Ofcourse this will break your site for a few seconds but at least you can go to the admin panel and rectify your mistake.

It is like choosing lesser of two-evils. Would you rather be locked out and have the site be broken. Or would you rather have the site broken but have the ability to fix it in seconds by simply undoing your mistake.

How to Create a Site-Specific WordPress Plugin

You may think that it may be super hard, but it really is not.

  • All you have to do is create a new folder in the plugins directory. Example: /wp-content/plugins/yoursitename-plugin/
  • Open a blank file and save it as “yoursitename-plugin.php”
  • Put the following code in the file:
    Plugin Name: Site Plugin for
    Description: Site specific code changes for
    /* Start Adding Functions Below this Line */
    /* Stop Adding Functions Below this Line */
  • Now upload this file into the folder you created in the plugins directory. Then simply activate the plugin.

From this point on, we will recommend adding the appropriate snippets we share into site-specific plugins rather than theme’s functions.php file.

We hope this will start a new trend that others will follow. We have already joined the band-wagon, and we recommend that you do this as well. It is a best-practice that will save you time in the long-run.

Editorial Staff at WPBeginner is a team of WordPress lovers led by Syed Balkhi. Page maintained by Syed Balkhi.

WPBeginner's Video Icon
Our HD-Quality tutorial videos for WordPress Beginners will teach you how to use WordPress to create and manage your own website in about an hour. Get started now »
  • WPBeginner Staff

    Make sure that your stored the plugin’s php file in /wp-content/plugins/ folder and not in your theme directory.

  • WPBeginner Staff

    You can try and fit your modifications in site-specific plugin by using filters. However, since you had to edit specific files we doubt that all your edits can be implemented in a site-specific plugin using filters. In that case you should make those changes into a child theme. All your custom CSS should also go into your child theme’s stylesheet. You can also use your site-specific plugin to enqueue a custom stylesheet.

  • Chelsey

    Thank you for your patience… I’m still trying to figure out how to ‘create a new folder to plugins directory’ :-)

    • Rodney Lacambra

      Hi Chelsey. Consider this guide:

      Go to “File Manager”. It will take you to “/public_html” directory. Click on “wp-content >> plugins” . This is where you will “create” a folder called “yoursitename-plugin”. After that, create a file using some text editor(notepad++), paste the code given above and save the file as “yoursitename-plugin.php”. Upload it to “yoursitename-plugin” folder and activate it in your wordpress admin area. Easy as that!

      Hope it helps you a lot.


  • WPBeginner Staff

    yes you can use it for multiple functions.

  • WPBeginner Staff

    Your code seems to be correct. Here is what you can do:

    Make sure you have saved the plugin file in the /wp-content/plugins/ directory.

    Make sure that your plugin file name is correct. We recommend using yoursitename.php format. For example if your domain name is black-circles then your plugin file name should be black-circles.php

    • SteveMTNO

      I originally had the plugin file (bc-plugin.php) in its own directory called blackcircles/wp-content/plugins/bc-plugins. That didn’t work.

      Then I tried moving the bc-plugin.php file from that folder to the blackcircles/wp-content/plugins folder. Still doesn’t show up in my admin panel.

      Do I have to “enable” it first before it shows up or something?


      • WPBeginner Staff

        If the file is correctly placed in your plugins folder then you will see it in your WordPress admin area under Plugins. If you see your plugin there, then you will have to click on the activate link below the file to activate the plugin.

        Did you try renaming the file to something else?

  • WPBeginner Staff

    There were spaces in your PHP opening and close tags
    is the closing tag there is no space between them. See the corrected version here and compare it with your code. Hope this helps

  • UgochukwuEmmanuelAgbams

    i got this message while trying to install it.

    The package could not be installed. No valid plugins were found.

    • WPBeginner Staff

      This usually happens when your plugin’s header is not valid. Please paste your code in and paste the link in a comment.

  • Joe Librizzi

    This is a fantastic post, thanks! Quick question – could this same method be used to modify an existing plugin, sort of like you can use a child theme to modify existing CSS? I know you can modify a plugin directly, but I’m trying to avoid losing the modifications when the plugin is updated.

    • WPBeginner Support

      Joe, yes this can be used to modify plugins. Another way to modify plugins safely is by changing their header information. You can use the header shown in the above code as an starting point.

  • Correen

    Successful! Thanks for showing me how to get this accomplished.

  • Chris

    I am new at this and learning as I go but I am confused as in the instructions both the singular and plural version of plugin was used. Am I to create one plugin file to put all snippets into or seperate plugins for each code/snippet/task?

    For example – I found this article by gooling for how to create more than one custom post type. Would I put each custom post type into a seperate plugin?

    Or could the code for custom post type go into the same plugin file as theme support for post thumbnails as I have it currently in my functions.php?

    • WPBeginner Support

      The code for all your custom post types can go in one plugin.

  • Shemul

    what about custom.css? can we made something like this. it is good to have child theme then.

    • WPBeginner Support

      A child theme is always recommended but there is a fine line as to how much functionality themes should have and what functionality should fall under plugin domain.

  • Sussie T

    Great article. I did this, and it was very easy. But now I am taking this further and made another file to my plugin for the site specific widgets. My first widget.
    Have fully created 2 widgets, but only the last one is showing in admin. I guess is something with hooks or register_widget, but i cant crack this one.
    Seams like an easy error to solve, if you got the experience. But for a beginner Google is not helping at all.

    Resume of my widget file:

    widget script
    widget script

    a function witch registers my 2 widgets

    Outside this function is add_action(widgets_init, name of above function)

    Please help

  • paul

    so when i read
    Paste this code in your theme’s functions.php file or your site-specific plugin
    i just create this site-specific plugin and add code to this rather than my functions.php

  • Duy Dang

    Thank you so much, it’s very useful!

  • Junior Godoi

    And what about mu-plugins folder?

  • Max

    Your site is god sent! I’ve literally been going through each of your tutorials, making a list of all the one’s I’m going to be implementing on my new site I’m developing. Some things you have covered, I would of never even have thought about, but now I am definitely dong them. Thanks for all the information you provide with your blog.

    • Editorial Staff

      Thanks a lot for the kind words Max. Let us know if you have any questions or suggestions by using our contact form.

  • Hamza Aid

    I’m managing a heavy loaded WP portal, and I found many problem when performing modifications because the developer made the same mistake, and put all the code (functions, etc..) in functions.php

    Now, I re-designed the portal, and separated many functions to site specific plugins. Thanks for this great post

  • Mattia Frigeri

    It must be said.
    This is a superlative post.

  • Greg

    I am not sure what it is I am doing wrong. I have done exactly as you have said and I can not get it to show in my WordPress Plugins.

    I have FTP’s it in, zipped it and tried to upload it via the admin and activating it (wp actually recognized it, and when I clicked the “Activate” link …. nada. It is like it was never there and when I FTP’d back in, it wasn’t there either.

    So I am trying Brent Logan’s plugin he mentioned (Code Snippets).

    Hopefully I’ll have better luck.
    I appreciate the article though. Thanks.

    (I am not that new to this. I have played with WordPress and Drupal and their plugins quite a bit. I am not sure why it is that I am having so much trouble with it.)

    comment would be appreciated — and I will keep reading here as well.

    • Editorial Staff

      That is actually very weird. Even when you FTP this, the file goes away from the folder?

  • Billy Patton

    …I tried to keep this method a secret. hahaha

  • Brent Logan

    I was doing this until I found the Code Snippets plugin. This plugin makes it easy to add multiple snippets, with a place for easy descriptions, and then activate or deactivate the snippets individually. Quite slick.

  • b.nijhoff

    I always thought it was really hard but after seeing this I now know I could do it to. Thanks for sharing this, all your articles have been really helpful so far. Keep on the good work!

  • ericsavina

    What I don’t get is that I keep reading everywhere that I should modify the functions.php instead of adding plugins. It is supposed to make the site faster. So, who should I trust? The idea of having a separate file for a the changes I’m making to the funtions.php file seems very interesting. At least, I would be able to easily update my theme without having to check every time the customs changes I made.

    • CreativeBoulder

      @ericsavina From what I have been gathering, and I’ve been doing this for a good while, is that the speed and performance using a ton of PHP in your functions.php versus additional plugins that use the same code– I was not able to find much of a difference in speed. Now, anybody correct me if I am wrong and if anybody has different performance comparisons.

      At this point, I’m using my functions.php file as I outlined to keep my functions organized along with a few custom plugins that I have designed with multi-site purpose. Hope that all makes sense.

      • ericsavina

        @CreativeBoulder Thanks for your answer. I will create this plugin and check if there are any differences in loading time.

        • CreativeBoulder

          @ericsavina Not a problem. Please let me know if you find out some different results than I did? Google Chromes Web Developer Tools have been more than helpful in performance and load-time and same with

  • CreativeBoulder

    I fully understand the reasoning behind this setup. I really like the concept. When WordPress Upgrades, then you might need to upgrade some of your functions instead of having to navigate a possibly unorganized file structure. I was thinking about this about a week ago when working on a client site and did this with my functions.php:


    // Require Administrator Functions/Classes


    // require Custom WP Plugins (By BusinessName)









    Which allowed me to basically work on certain aspects and know where certain custom widgets or shortcodes were instead of a huge functions.php file. What do you think? Which method works better for you?

    • affanruslan

      @CreativeBoulder No, this function.php file is within your theme file, not the core wordpress file :)

      • CreativeBoulder

        @affanruslan I fully understand what the concept here is. Thanks for the reply. The goal of creating a Site Specific Plugin is to keep your functions, widgets, short-codes (etc) separate so that they are easier to work with and more organized. My concept of using your Theme Specific functions.php and “modularizing” it into separate files is just as easy to stay organized. That’s what I was getting at. I appreciated this post. =)

  • tomdana

    At first I was confused on what this Post was about. Once I read it I realized the usefulness of doing exactly what you suggest. I named my plugin “site-specific-functions”. Thanks for the information and all you do.

  • tomdana

    At first I was confused on what this Post was about. Once I read it I realized the usefulness of doing exactly what you suggest. I named my plugin “site-specific-functions”. Thanks for the information and all you do.

  • fergusonsarah

    It’s really great to read such a valuable blog post here, thanks for sharing.