If I create a custom module for a single site where should I put it? Previously I would put it in sites/all/modules, or possibly sites/all/modules/custom. However I just read this article, Creating Your First Module in Drupal 7 Module Development which say the best practice is to put them in sites/default/modules:

However, as of this writing, /sites/all/modules is not the recommended place to put custom modules unless you are running a multi-site configuration and the custom module needs to be accessible on all sites.

The current recommendation is to put custom modules in the /sites/default/modules directory, which does not exist by default. This has a few advantages. One is that standard add-on modules are stored elsewhere, and this separation makes it easier for us to find our own code without sorting through clutter. There are other benefits (such as the loading order of module directories), but none will have a direct impact on us.

We will always be putting our custom modules in /sites/default/modules. This follows Drupal best practices, and also makes it easy to find our modules as opposed to all of the other add-on modules.

Is this really considered the current best practice? Is there some official reference to this?

2 Answers 2


Modules can live in many places. If you use Apple's OSX it's alot like where Applications and Fonts can live in OSX ...

Modules can live at:

  • /profiles/PROFILENAME/modules/
  • /sites/default/modules/
  • /sites/all/modules/
  • /sites/SITENAME/modules/

core drupal modules are found in DRUPAL_INSTALL_DIRECTORY/modules.

Where a module lives deems how drupal sees it.

  • Modules in a profile directory can be seen by sites installed by that installation profile.
  • modules in /sites/default can only be seen by the default drupal site.
  • modules in /sites/all path can be seen by all drupal powered websites regardless how they were installed, or what subsite they are.
  • modules in /sites/SUBSITE/modules can only be seen by that subsite.

In general it is best practice to place the module folder where it is needed for its scope of use in your Drupal installation.

Additionally, it is a best-practice to place subfolders such as:

  • /sites/SUBSITE/modules/contrib
  • /sites/SUBSITE/modules/custom

to distinguish within a modules directory what is standard 3rd party contributed modules used for a site, and what is custom built drupal modules by your company in /custom.

Yes, there is documentation on this in your drupal installation folder at /sites/all/README.txt

Note: alot of this changes slightly with drupal 8

EDIT - references on /contrib and /custom directories.

Basically at some point in drupal development you want to organize your modules more and more, per site, per drupal installation. Many developers use these types of conventions. Drush Make (bundled into core Drush as of 5.x) allows specification of a subdirectory within /modules to place a module.

  • Can you provide a reference for the best practices, particularly the contrib and custom subdirectories? The README.txt doesn't go this far (and as far as I can tell, that language only appeared in 7.17).
    – mpdonadio
    Commented Nov 21, 2012 at 19:53
  • I did look briefly for official documentation on /modules and subdirectories. I know the README.txt talks about placing modules there. Having used Features and attended 3 DrupalCampLA's recorded session talks go over this. A feature is just a module, but its not contrib and is usually custom so these "best practices" become commonplace as the extent you utilize drupals capabilities expands.
    – tenken
    Commented Nov 21, 2012 at 22:08

Drupal looks for modules in the following directories, and in their sub-directories:

  1. profiles/$profile/modules, where $profile is the name of the currently used installation profile

  2. sites/all/modules

  3. $config/modules, where $config is the directory containing the settings.php file currently used from the website

When you are using the default settings.php file, the last directory becomes sites/default/modules. Really, the last rule is thought to load the modules from, for example, sites/blog.example.com/modules, where sites/blog.example.com is the directory where Drupal looks for the settings.php file for http://blog.example.com.

If you are using the Update manager module, the modules should be copied in sites/all/modules, which is the directory where the module copies the modules when it updates them. If you are not using that module, and you have different teams that handle different sub-domains/domains for a multi-site Drupal installation (to which you give different access permissions to the directories containing the modules), then you could use $config/modules for the modules.

If you have a single domain, or you are not using a multi-site configuration, sites/all/modules is the directory I would use. Even in the case of a multi-site configuration, I would still put the modules in sites/all/modules, as it allows me to have a singe copy of the module for all the sub-domains/domains.

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.