Warning message

Documentation is currently being migrated into the new system. Some pages might be temporary missing, and some guides might appear empty. Thank you for you patience while we are improving Drupal.org documentation.

Installing modules

Last updated on
August 23, 2016 - 07:29

You can add third-party contributed modules to extend or alter Drupal's behavior.

Table of contents:

In a nutshell

1. Download the module and extract it in the folder sites/all/modules/contrib. It is recommended to place all third-party modules in a subfolder called contrib.

2. Go to the Module page at Administer > Modules (http://example.com/admin/modules) and enable it.

3. Read the module's documentation (readme file or on-line here on drupal.org) for further configuration instructions.

Note: The drush commands drush dl module_name and drush en module_name offer probably the fastest way installing modules.

Choose the module file

Choose the right release. When you have chosen a module to add to your site, you must choose which release to use. The version must be compatible with the version of Drupal you are using. Note that 'Development releases' are versions of the module that are in an active stage of development. They may be written for a previous/current/future version of Drupal, are considered unstable, and should be handled with care. 'Recommended releases' are stable and ready to use.

Upload the module

There are two basic ways to upload module files to a Drupal 7 site:

  • Through the Drupal user interface
  • Manually on the server

The first option will not work on many types of servers, but may be a more user-friendly choice on servers where it does work. The second option is always available.

Option 1: Upload the module through the Drupal interface

upgrade manager icon for installing new modules

  • Navigate to the install page. Navigate to Modules > List (tab), or http://example.com/admin/modules, and click the link 'Install new module.' (You must have the Update manager module enabled to see this link. For those new to Drupal, go to "Modules", find "Update Manager," put a check mark in the box by "Update Manager" and then click "Save" at the bottom of the page. You should now have a link to install new modules.)
  • Follow the prompts. You will be prompted to provide either the URL to the download, or to upload the .tar.gz or .zip file from your local computer. Click 'Install', and the Update manager will copy the files into your sites/all/modules folder. (See Update manager for more information about what that core module can do.) The next screen gives you two links. Click 'Enable newly added modules' and skip down to the 'Enable and configure' section.

    Update manager for installing a module

If your site asks for your FTP username and password, it is referring to the username and password to access your site, not drupal.org

A note about FTP: If FTP is not enabled for your server, you may receive an error message. Drupal will not be able to diagnose the problem, only tell you that there is one. It's up to you to determine whether your server is properly configured for FTP.

Option 2: Upload the module manually

  • Extract the files.The downloaded module package will be in a compressed file format such as 'tar.gz'. On Windows, use a program like 7-zip to extract the files. On modern Mac systems, double-click the .tar.gz file. On Linux or similar systems, use the command line:

    tar -zxvf modulename-drupalversionnumber.tar.gz
    You should see a list of files extracted into a folder.

  • Upload the folder. folder placement for contributed modulesTransfer your files with SFTP or FTP to the desired modules folder in your Drupal installation (or if you are using version control, add and commit them to your code repository). The modules folder at the top level of your Drupal installation is reserved for Drupal core modules (the ones that come with the original download of Drupal). Contributed modules belong in sites/all/modules. If you are running a multi-site installation of Drupal, use sites/my.site.folder/modules for modules there that are specific to a particular site in your installation. Modules that will be shared between all sites should be placed in sites/all/modules.

Please note: Especially for sites with a lot of additional modules, many people have begun to further divide the modules folder, to help stay organized. A typical way of doing this would be:

  • sites/all/modules/contrib for all contributed modules.
  • sites/all/modules/custom for all custom modules.
  • sites/all/modules/features if you have additional modules that were created using Features.

Enable and configure

  • Read the directions. If the module has an installation file (usually INSTALL.txt and/or README.txt), read it for specific instructions. There are modules that require special treatment, and even modules that depend on other downloaded files to function properly. Sometimes the README file has no .txt extension. If you double-click it, your computer won't know what program to use. In that case, open a text editor first, and then open the file using the editor's 'file open' command.
  • Enable the module. Navigate to Administer > Modules or http://example.com/admin/modules. Check the 'Enabled' box next to the module and then click the 'Save Configuration' button at the bottom. Note: If you are updating an existing module, you'll need to click 'update script' at the top of the page or load http://www.example.com/update.php, then click 'Continue' (after making a backup of both your database and 'sites' folder).
  • Set up permissions. Some modules will require that you change permissions to get them working. Permissions information may be in the instructions that came with the module. Navigate to Administer > Modules and click on the 'Permissions' button for the desired module. placement of configure and permissions buttons for modules in Drupal 7You can also do this on the Permissions page (Administer > People > Permissions). Scroll down to see if the module appears in the list and, if it does, give the appropriate permissions to desired roles.
  • Adjust settings. Most modules will have some type of settings page. It will vary from module to module but if not described in the README.txt file, it can usually be located by navigating to (Administer > Modules) and clicking on the 'Configure' link for that module. Not all modules have settings pages.

Please note: You can only have one copy of a module with the same name in each Drupal site. The module's name is determined by the name of the .module file, not by the name of the directory.

Tip: If you run into problems, search the module's issue queue and the forums. If your problem hasn't already been addressed, post a question or issue and someone will try to help you out.

Tip: To keep up-to-date on any issues and fixes related to your newly installed module(s), you can create a user account on Drupal.org (if you haven't done so already) and then subscribe to the feed of each module you are using.

For a collection of useful materials for module developers, see Module Development with Drupal.

Installing sandbox projects

On occasion you may wish to try out a sandbox or experimental project. A sandbox project is a module or theme that contains experimental code that is not yet ready for general use.

Sandbox projects are not packaged for download, so the usual way of getting them is by "checking them out" using Git, the software used for managing Drupal code.

If you haven't used Git before, the good news is that it should be relatively quick and painless.

  • Install Git, see the handbook guide.
  • From the sandbox project's page, click the "Version control" tab above the project description and follow the (one step) instruction for "Setting up repository for the first time".

This will get you the project code, which you can then install on your site like any other module or theme.