Use mu-plugins for adding custom functionality to your WordPress site

If you google “functions.php” you get about 7 million results. I bet most of them contain bad advice: “How to add functionality to your WordPress site”. Some of them continue even worse: “[…] without using a plugin”. For your own good, don’t edit functions.php to add custom functionality to your WordPress site. You can use mu-plugins to do that.

If you’re customizing your theme – the templates that are responsible for the output and formatting of your site, then you’re sometimes OK with editing functions.php. As long as either of these conditions is true:

  • You are using a custom theme that you are maintaining yourself. I.e. you didn’t download it from somewhere.
  • You have created a child theme, and are editing the child theme’s functions.php (which basically makes your theme the above bullet point).

If both of these are false and you’re editing functions.php, all your changes will be lost the next time you’re updating the theme.

functions.php is where functions used by the output templates in the theme is defined. This is not where you add any custom functionality.

A Theme modifies the way the site is displayed, without modifying the underlying software.

– The WordPress Codex

Not sure if the code you are adding belong in functions.php or not? Consider this: Is this functionality you want to keep if you change the theme? If your answer is “no”, then you’re probably OK with adding it to your custom made (child) theme. If the answer is “yes”, then your better option is to create a plugin.

Plugins are ways to extend and add to the functionality that already exists in WordPress.

– The WordPress Codex

Must-Use Plugins (mu-plugins)

In addition to plugins, WordPress has a nifty less-known feature for loading custom functionality called “Must-Use Plugins”, or “mu-plugins” for short. These special mu-plugins are loaded before all other regular plugins, and they can’t be deactivated. If you are running a multisite network, the code in these mu-plugins will be loaded on all the sites in your installation. If the code shouldn’t run on all the sites, you better make an option to whether your mu-plugin should run any code or make it a regular plugin instead.

If you have a regular single site or are sure that you want the code to run on all sites, then creating an mu-plugin might be a very good choice for you.

A nice feature of mu-plugins is that they can be so extremely simple. To add an mu-plugin, all you have to do is to drop a PHP file into the wp-content/mu-plugins directory. This directory isn’t created by WordPress by default, so if you don’t have any mu-plugins already, you likely have to create it yourself first. All PHP files directly in this directory (not in subdirectories) will automatically be loaded by WordPress quite early in the execution – before any other plugins. This means that you can also use mu-plugins to modify any plugin behavior that can be overridden or extended with filters and action hooks.

Here’s an example mu-plugin that adds a paragraph to the end of all posts. To use this, just drop the code into a PHP file, e.g. twitter-follow.php in the mu-plugins folder:

add_filter( 'the_content', function( $content ) {
    return $content . '<p>Thank you for reading this post!</p>';
} );

That’s really all that’s needed. So simple and easy, and you don’t have to worry about creating child themes or plugins.


  1. Thanks Bjørn Johansen,

    I just found out about the mu-plugins today and came across your post while doing further research. Thank you so much especially for the example php code.

  2. Function in mu_plugin is working in index.php file but that particular function is not working in custom template file. why this is so?

Comments are closed.