What is the mu-plugins folder?

Users of WordPressMU have long been aware of a folder within wp-content called mu-plugins. Obvious conclusions were drawn because of the name and where it was, but this actually stands for “must-use” plugins. Why? Because any code (plugin) placed in the folder is run automagically, as if it were part of WordPress itself. (Yeah, that label was news to me too.)

Support for this folder has actually been in single WordPress since 2.8.

In WPMU, you never saw any reference to this folder from the backend at all. Just drop the code in, and the plugin was already running.

In 3.0, support for this is naturally still there, but the folder isn’t created for you. If you do encounter a plugin (like domain mapping) that needs to run in this folder, simply create it via FTP or through your web host’s control panel.

Also in the backend, if you are using the mu-plugins folder, is this:
the plugins menu tabs

A listing! You’ll note on this example site (other than we really need to clean out the plugins we were testing), must-use plugins are now listed. This will only be visible to Super Admins – regular administrators, even with access to the Plugins menu, will not see this.

While you may be tempted to toss all your plugins in there – don’t. Like stated above, the code placed in here runs automatically and (depending on how the plugin is coded) on every single page load. Also, any files in folders will not be seen. There must be a physical php file there to be read.

Popular plugins that do belong in this folder are ones like Domain Mapping and New Blog Defaults. Please make sure to always read the readme.txt included with any plugin, as it will specifically state if it should be installed in this folder.

22 Comments

  1. Very cool article. I have the feeling I have a lot of things to learn that come from the WPMU world 🙂 (didn’t noticed it had been implemented in WP 2.7)

  2. I had ignored the installation instructions to use that directory, but have gone back and corrected my mistake. Great tip — thanks!

  3. […] I found you don’t need to use the “mu-plugins” folder, It turns out there is a good reason to use the mu-plugins folder and it stands not for “multiuser” but “Must Use”; but IMPORTANTLY, you DO […]

  4. Thanks for the article .

  5. Am I crazy, or is it true that you no longer need to create the mu-plugins directory in order to get the same effect? In my Multisite-enabled install of WordPress 3.0.1., I’m seeing “All | Active | Inactive | Network | Update Available” links; the plugins under “Network” seem to function like the “Must-Use” plugins. When I install new plugins, the options “Activate | Network Activate | Deactivate” usually appear for each plugin.

    • Not exactly. 🙂 Network activate does activate the plugin across all blogs on the network, but that’s not *quite* the same function as the mu-plugins folder.

      If the plugin’s readme file says to put it in mu-plugins, then do so.

  6. Thanks for posting this Andrea. I was one of those that thought it stood for the MU of WPMU 🙂

    The beauty of wordress, you learn something new every day!

  7. I think most users miss this very important bit:

    Also, any files in folders will not be seen. There must be a physical php file there to be read.

    Now most of the newer plugins have their own folders. I tried experimenting to put only the main plugin file of those into this mu-plugins folder – and they do show up listed under Must Use.

    I wonder how functional they would be having only the main php file there…?

    Any insight?

    • If it’s designed to go in the mu-plugins folder, dump all the files from the folder into mu-plugins.

      Or, some plugins have very specific instructions to move one particular file from the folder into mu-plugins.

      Like I said, always read the readme. 🙂

      • (just for the record: I am the proverbial one in a million that reads not only the readme files but even the 4 pages small, grey print on credit card applications ;))

        I see at least two issues here:

        1. The vast majority of the plugin authors for pre-3 WP never thought their plugins might be used in a WPMU/WPMS environment, so there is nothing about it in the readme files.

        2. This Codex page never mentions the “one dingle php file” requirement, so users simply try to upload the plugins to the mu-plugins folder and go nuts because those plugins never show up in their admin panel 🙂

        Except this post I couldn’t find any reference to the ‘physical php file’. Actually, I didn’t even know what to search for until I figured out by trial and error that I needed to use only one-file plugins.

        So, thank you for the post!

  8. depeneds on the plugin, if it has more than one file moving over the main file probably won’t work and you’ll need to do the whole folder.

    If that’s the case I usually create a blank file with the name of the main file in the root of mu-plugins and include the main file located in the folder.

    • Great, thanks for the info.

      By “include” you mean a simple php include? Can you, please, give an example?

      • yes, exactly. Just a normal php include will do.

        I’ll give my login with ajax plugin as an example. Just move the login-with-ajax directory into the mu-plugin folder and create the following file in the mu-plugins folder:

        wp-content/mu-plugins/login-with-ajax.php :

        That’s it. WordPress will now auto-activate this plugin.

        • oops, code won’t work with php tags…

          the file would contain this line inside php tags:

          include(‘login-with-ajax/login-with-ajax.php’);

          that’s it

  9. I appreciate the lightening fast reply and explanation: “put the plugin file itself directly in the mu-plugins folder, not its enveloppe folder” – and wow it appears.
    Great! Thanks

    PS : my first comment entry automatically generated a twitter link but its an invalid one??

  10. “New Blog Defaults” <- I am SO glad you mentioned this plugin, because I didn't know about it.

    The readme file on this says: "Settings will only affect new blogs". Does this mean that all MU plugins that we intend to use should be included at the time we perform the install of WP, or else it is too late?

    • The plugin you refer to will change certain settings when you register a new blog, therefore old blogs won’t be affected by this plugin.

      For mu-plugins folder, you can add plugins whenever you want, just like the normal plugins folder, except the plugin is automatically activated.

  11. thanks Andrea informative post, must use learned it for the first time was having something in my mind reading the codex on Create_A_Network plugins information there
    my MU installations were prior 3.0 so i had that folder there but now i am installing or say revamping using 3.0.3 lo behold no mu-plugins folder hey where would i put my reCAPTCHA plugin? instatnly shot a tweet to Donncha his reply is yet to come you helped me in a big way

    i always say i know three people when it comes to WordPress MU, Donncha, Ron, Andrea (you)

    thanks sis

  12. Finally I got the real difference, hallelujah! The tip with the listing is extra-cool. Thanks!

Leave a Reply