Installing Modules

Last updated on
21 January 2017

This documentation is incomplete. Add more information.

In Drupal 7, there was a distinction between "installing" a module and "enabling" it. As it turned out this would often lead to cases where people would disable a module and remove its code without ever cleaning up the database. As a result, the approach was changed in Drupal 8 so that one's only options are to install the module - which registers its routes, hooks, etc. with Drupal and creates any necessary entries in the database and "uninstall", which removes any database entries and de-registers the routes, hooks, etc.

 

  1. Understand the various module versions available

  2. Codebase and database overview

  3. Module location in the codebase

  4. Importing the module

  5. Enabling modules

  1. I recommend that if you are trying out modules that you have Not used before, only install one 'new-to-you' module at a time. And before you move on to another module, test the first module as thoroughly as necessarily to see how it changes things on your site, in particular, whether or not it breaks things that are already working.

    'Lower-case only' alphabetic character use in folder and file names

    I recommend that you always use only lower-case for the alphabetic characters in your Drupal site's folder names, and file names. You will never have a problem if you follow that simple recommendation.

  1. Find a module to use

       | Contents at this point ⤴ | 

    Go to the main page for contrib Modules from drupal.org ~ drupal.org/project/project_module ⎘.

    [ Themes: contrib Themes from drupal.org ~ drupal.org/project/project_theme ⎘]

    That page is the 'Modules' sub-tab of the drupal.org main section 'Download & Extend'

    Core compatibility: "8.x" - Set the fourth item down from the page-top, 'Core compatibility', to "8.x".

    Other search options: Feel free to change any of the other search items. You can also put a keyword or two in the textarea box for 'Search modules'.

    The item 'Sort by' is, by default, set on "Most installed", which means that the search results will be sorted by the most-popular first.

    Click the button "Search".

    On the search results page, the 'name' of each module (or theme) is a link to its home-page, known at drupal.org as its 'project' page.

    Click on the name of a module (or theme you would like to investigate further.

  2. Module project page

       | Contents at this point ⤴ | 

    This section is an overview of a few things of importance on project pages. In addition to contrib 'modules', contrib 'themes' are also known on drupal.org as 'project'(s), and all drupal.org project pages have the same basic layout.

    Module project pages vary in depth of detail, however, because the content of each project page is created by one of the module's developers.

    The project page is usually worth reading carefully.

    Among other things, if the module is dependent on another module(s), or possibly an extra 'library'(s), that information will be posted. It is not critical if you forget about a module or library dependency, however, because later when you try to enable or use the module, you will get a notice about what you are missing.

    'Downloads' section

    A project page will always include links to get the various versions that are available for that module.

    Those 'Downloads' links will be discussed in more detail in the next section, Understand the various module versions available on its project page ⤵.

    'Issues for...':

    The module's project page will always include links under the heading 'Issues for...'. Those links are in the right-hand column when your browser window is wide enough, or they are near the page bottom under the 'Downloads' and 'Maintainers for...' sections when your browser window is narrower.

    The 'Issues for...' links take you to the issues queue for that specific module project. The issues queue is the official place where all of the problems ('Bug report'), support requests, ('Support request') and new-feature requests ('Feature request') can be found and searched for.

    So, if you run into problems with a module, search the module's issue queue. If your problem (or request) has not already been addressed, post your question or issue using the link 'Create a new issue', and someone will try to help you out.

    Resources:

    Just under the 'Issues...' section, in the section under the heading 'Resources', I always look for the link 'Read documentation'. That link will not always exist, but if it is there, it is a link to what the project's developers consider the most useful information for their project.

    The 'Read documentation' link might take you to a page on drupal.org in the 'Documentation' section, or the link might take you to a page off of the drupal.org site.

    Generally speaking though, every contrib module will have a "README.txt" file and/or an "INSTALL.txt" file in its top-level folder that you can view after you download the module, or after you import it into your site.

    The various Documentation resources available for a module (or theme) will be discussed in greater detail near the bottom of this page, in the section Module documentation and help ⤵, but notably at this time, you can view any project's 'README.txt' file, or see its other documentation without downloading anything, by following the instructions below in the 'Module documentation and help' sub-section Module "README.txt" file ⤵

  3. Understand the various module versions available

       | Contents at this point ⤴ | 

    On the "project" page, see the section 'Downloads' under which are the sub-headings 'Recommended releases', 'Other releases', and 'Development releases'.

    The picture below is for Drupal 7, but hopefully you get the idea.

    Table of Drupal module versions categorized by 'recommended', 'other', and 'development' versions

    The version you choose must be compatible with the version of Drupal you are using. So since you are using Drupal 8, you can only use a 'Version' that begins with '8.x-...'. But do not worry. If you try to use a Drupal 6 or 7 version on a Drupal 8 site, your site will not allow it to be used.

    'Recommended releases'

    Look for the uppermost 'Version' that you can find for Drupal 8. That is the version that you should try first, and hopefully it will be under the sub-heading 'Recommended releases', which means that it is stable enough to use on a live site (also known as a 'production' site).

    'Other releases'

    If no 'Recommended releases' is available, your next best option is to try an 'Other releases' version, if available.

    'Other releases' are generally on their way to becoming a 'Recommended releases' version.

    But, on the other hand, on a rare occasion an 'Other releases' version is an older stable version of the module before major changes were made to it. In that somewhat rare case, the older stable version will have been moved from the 'recommended releases' when the newer version was ready. One reason for keeping an older version around in the 'Other releases' section would be if some other separate module project were dependent on the older 'Other releases' version for that dependent module to work properly.

    'Development releases'

    The 'Development releases' version of the module is in some stage of development.

    It is the current 'state of the art of development' version, as the developers are working out bugs, or are adding new features.

    Be aware that the 'development release' might be being prepared for a future version of Drupal. Taking Drupal 8, for example, even though today Drupal 8.1 is the current recommended version of Drupal 8 core, the module's 'development release' might be being prepared for future use with the Drupal core version 8.2, or 8.3, which will have features not found in the current 8.1 core version.

    'Version' column

    This column is for the version number of the module on that row.

    For more information about the version numbering scheme that is being used, go the drupal.org page Version numbers ⎘.

    'Download' column

    This column contains the download links you use to actually get the module.

    *.tar.gz versus *.zip file formats for all project downloads #

    Each module is available in both the *.tar.gz and *.zip formats. Each of these files contains all of the module's files and folders in a single file that has been archived (multiple files and folders into one file), and compressed (made small as possible).

    The *.tar.gz version is smaller, but the contents of the *.tar.gz and *.zip files are identical.

    MAC and Linux users should use the *.tar.gz version

    Windows users:

    Use the *.zip version if you intend to extract the file onto your computer.

    Additional *.tar.gz & *.zip info, and for all your 'freeware' needs

       | Contents at this point ⤴ | 

    For more information on *.tar.gz and *.zip files, including where to get free programs to work with them for Linux, MAC, and Windows, so that you can more easily 'extract' them, or create them on your computer (versus, for example, the limited built-in program within Windows), go to the drupal.org page that discusses this in more detail using the theme Zen project as an example. It starts at the heading *.tar.gz versus *.zip ⎘ and continues through the "For all my freeware needs,..." discussion.

    Leave the project page open

    We will return to the project page for your module later in this guide when it is time to actually import the module, so just leave it open.

    • A Windows extraction of a *.zip file onto a personal computer is a one-step process. If, however, you extract the *.tar.gz file onto your Windows computer using, for example, the built-in Windows tool, (that was first introduced in Windows 7, or 8) the extraction process will first extract the *.tar.gz file to a *.tar file, and then you will have to repeat the extraction process with the *.tar file to fully complete the extraction.

      Granted, as a Windows user, if you are only grabbing the download link for an automated import of the module using the steps below in the section 'Automated module import with URL', then either version would do. Similarly, if you are only downloading the file onto your computer before using the automated import method detailed below under 'Automated module import of local file', then either version would do.

      In other words, Windows users will only find difficulties when they are extracting the *.tar.gz file onto their computer, because of the two-step requirement, and because older versions of Windows do not have a built-in tool for extracting *.tar.gz files.

      In conclusion, Windows users: Use the *.zip version.

  4. Module location in the codebase

       | Contents at this point ⤴ | 

    All of the module's (or theme's) files and folders will be contained in a single parent folder in your codebase. That parent folder will be named similarly to the module itself, using lowercase-alphabetic characters, and occasionally the underscore character ("_") between multiple words.

    When you import a module into your Drupal codebase using either of the two automated processes discussed below, the module will be placed at the default recommended location:

    [d8-root]/modules/*NEW-SINGLE-MODULE-FOLDER-HERE*/*MULTIPLE-MODULE-FILES-AND-FOLDERS-HERE*.

    [Themes default location: [d8-root]/themes/*NEW-SINGLE-THEME-FOLDER-HERE*/*MULTIPLE-THEME-FILES-AND-FOLDERS-HERE*]

    Manual import location

    If you import a module 'manually', you should place your module in that same default recommended location, *HERE*:

    [d8-root]/modules/*HERE*

    [Themes: [d8-root]/themes/*HERE*]

    After you perform a manual extraction of a *.tar.gz or *.zip file, be sure to check the file/folder structure to make sure that the module's folders are in the proper place, and are structured properly. This will be discussed below in more detail at Check file/folder structure after manual extraction ⤵

    Other possible locations

    While it is possible to use locations other than the default recommended location for modules, you should have a very specific reason for using any other location.

    One legitimate exception would be, for example, if you are running a Multisite Drupal ⎘ with several Drupal sites sharing the same codebase, and you want your new module to only be available to a 'specific_site'. In that case, the module should go into the folder:

    [d8-root]/sites/specific_site/modules/*NEW-SINGLE-MODULE-FOLDER-HERE*

    [Themes: [d8-root]/sites/*specific_site*/themes/*NEW-SINGLE-THEME-FOLDER-HERE*]

    {{COMMENT: I am guessing about the proper location for a site-specific module in a multi-site Drupal 8 installation. That may NOT, in fact, be correct for Drupal 8 as it was for Drupal 7. If you know otherwise, please correct the paragraph above. If you know I guessed correctly, please delete this comment. Thanks.}}

    Otherwise, with a multi-site setup, if a module will be shared between all sites, it should be placed in the normal default recommended location:

    [d8-root]/modules/*HERE*.

    [Themes: [d8-root]/themes/*HERE*

    For simplicity sake

    The rest of this page will be based on your using only one Drupal website, and Not a multi-site setup.

    Do Not use the core 'modules' folder

    Be careful not to use the Drupal core 'modules' folder for your new module.

    The 'modules' folder that resides at [d8-root]/core/modules is reserved for Drupal core modules (the ones that come with the original download of Drupal). Your contrib modules should Not be placed there. They could go there, but they should not.

    [Folder reserved for 'core' themes: [d8-root]/core/themes]

    If you keep your contrib modules out of [d8-root]/core/modules, that makes it easy to update your site later, because you can delete the entire [d8-root]/core/modules folder, and replace it with the updated version of the core [d8-root]/core/modules folder.

    Themes, likewise: If you also keep your contrib themes out of the core 'themes' folder at [d8-root]/core/themes, when you update Drupal core, you can delete the entire [d8-root]/core folder, and simply replace it with the updated version of the [d8-root]/core folder.

    Using sub-folders of the 'modules' folder

       | Contents at this point ⤴ | 

    Some advanced users who intend to modify the contrib modules, or to create modules of their own, or who simply have a lot of contrib modules, organize their non-core modules in sub-folders of the contrib 'modules' folder [d8-root]/modules.

    Keep in mind that each module must be unique in both the 'machine name' used for its folder name, as well as the name it uses in the *.info.yml file.

    {{COMMENT: If the above paragraph is not entirely accurate, or if you can think of a better way to phrase it, or if you can add more details for clarity, please 'Edit' this page, or add your suggestions using the 'Discuss' link. Thank you.}}

    A typical organization scheme might be:

    If you put your new module into a sub-folder of the 'module' folder before you first use it, then you can rest assured that Drupal will use your new module without any problem.

    Moving modules that have already begun to be used

    If you want to move modules that you have already begun using on your site, see the page Moving modules and themes [This is a Drupal 7 page] ⎘.

    • [d8-root]/modules/contrib
      for original versions of contributed modules

    • [d8-root]/modules/custom
      for all custom modules

    • [d8-root]/modules/features
      for modules created using the 'Features' contrib module ⎘.

  5. Importing the module

    Importing a new module (or theme) into your site can be done in several ways. From a beginner's stand-point, the three ways are:

     - Automated module import with URL
     - Automated module import of local file
     - Manual module import

    Module import - Overview

       | Contents at this point ⤴ | 

    The process of getting your module into your codebase is at times referred to, elsewhere, as 'installing' the module. I use the word 'import' instead of 'install', because the import methods discussed below simply place the module into your codebase. Until you enable the module, it is dormant, and unused by your site.

    The two 'automated' methods are accomplished using your browser in the administrative area of your site, just like any other task you might perform on your Drupal site. The two automated methods can be used for both 'local' and 'online' sites, and are occasionally referred to as using your Drupal site's front-end UI (User Interface).

    The 'automated' methods take care of placing the module where it goes in your codebase, and also takes care of extracting the module's file and folders from the *tar.gz or *.zip file.

    The automated import processes will extract all of the module's files and folders into your codebase at

    [d8-root]/modules/*NEW_MODULE_HERE--A_SINGLE_FOLDER*/*MULTIPLE_MODULE_FILES_AND_FOLDERS_HERE*

    [Themes: [d8-root]/themes/*NEW_THEME_HERE--A_SINGLE_FOLDER*/*MULTIPLE_THEME_FILES_AND_FOLDERS_HERE*]

    'Automated import' is not allowed by some servers

    I have read that some servers do not allow the two 'automated' methods of importing a module. I do not know any of the details of that sad situation, but I assume it relates only to 'online' sites. If this is the case for you, use the third method, 'Manual module import'.

    I can only guess that if this is a problem for your online site, it is related to the fact that an online site normally uses a directory level somewhere above 'public_html' to temporarily store the *.tag.gz or *.zip file while it extracts the files and folders to your site; And, that your webhost does not allow your account to access that higher level. Contact your webhost provider, and see if the problem can be resolved for you.

    If you need a 'Drupal friendly' webhost without this issue, and which also gives back to the Drupal Association, check out the discounted 'new account rates' from several providers at the drupal.org page Drupal Shared Hosting ~ drupal.org/hosting ⎘.

    Automated module import with URL - Overview

       | Contents at this point ⤴ | 

    With this first automated method, you go to the module's project page at drupal.org, and copy the URL for the version of the module you want to use. You paste that URL into the appropriate box on the appropriate page of your site, and click "Install".

    If your site is online, this process is particularly fast, since it involves two online servers talking to each other, and bi-passes your personal computer. And, my online webhost server also extracts files at least ten times faster than my home computer can.

    Pros: You do not have to download the module, you do not have extract it, and you do not have to worry about putting it where it goes in your codebase.

    Automated module import of local file - Overview

    With this second automated method, you start with the module in a *.tar.gz or *.zip file on your computer.

    That file will usually be the one that you downloaded from the module's project page.

    The *.tar.gz or *.zip file might also be a *.tar.gz or *.zip file you created yourself after having made custom changes to the module. That is a fairly uncommon thing to have to do, however, and I have never had need to do it myself.

    With the *.tar.gz or *.zip file on your computer, you go to the appropriate page on your Drupal site, you click the button 'Browse', and navigate to the file's location on your computer. Then, click "Install".

    Pros: You do not (usually) have to extract the *tar.gz or *.zip file after downloading it, and you do not have to worry about where the module goes in your Drupal codebase.

    Manual module import - Overview

       | Contents at this point ⤴ | 

    The 'manual' method amounts to your manually put the module where it belongs in your codebase.

    That will either be locally on your computer, or at an online site by uploading it with your webhost Control Panel, or with SFTP.

    Also, you must manually extract the module's files from the *.tar.gz or *.zip file, either before importing it, or after.

    A manual import for a 'local' site running on your computer is not really such a chore, particularly if you are already familiar with using *.tag.gz or *.zip files.

    With a manual import to an 'online' site, it is much faster to upload the module as a single *.tar.gz or *.zip file, as opposed to uploading the multiple files and folders from an extraction of the *.tar.gz or *.zip file.

    The import methods work for 'themes' also

     | Contents at this point ⤴ | Jump over this. ⤵ | 

    It is worthy of note that all three of the import methods apply equally to contrib 'themes'.

    The only difference is that the recommended location for contrib themes is different that the recommended modules folder.

    The themes use the 'themes' folder, and the modules use the 'modules' folder. Those two folders are 'siblings' to each other, with 'sibling' meaning that they are together in the same parent folder. They are, in fact, together in the Drupal 8 root-directory (folder) of your site.

    For the two 'automated' import methods...

    You can use either the 'Install new module' button near the top of the 'Modules' page, or you can use the 'Install new theme' button near the top of the 'Appearance' page, to import either a module or theme.

    The respective addresses you will see in your browser's address bar are
    [d8-root]/admin/modules/install
    and
    [d8-root]/admin/appearance/install
    but both pages are essentially identical, and will work fine with either modules or themes.

    You will Not, however, see 'Install new module' and 'Install new theme' on the 'Modules' or 'Appearance' page, if the Drupal core module 'Update manager' is not enabled. That is the subject of the next section.

    Enable the Drupal core module 'Update manager'

     | Contents at this point ⤴ | 
     | Jump down to sub-section "Security: Enable 'Update manager' regardless" ⤵ | 
     | Jump down to section "Module import - The steps" ⤵ | 

    Both of the automated import methods require that you have the Drupal core module 'Update manager' enabled. For security reasons, however, you should have it enabled regardless of whether or not you intend to use those import methods.

    Your 'Update manager' might already be enabled, but it will Not be if you disabled it, of course, and it will Not be enabled if during the browser-based installation of your Drupal site, you did not leave the check-mark for the box "Check for updates automatically".

    Check to see if the 'Update manager' is enabled by going to your 'Extend' page.

    At the 'Extend' page, scroll to the bottom of the top section 'Core'. If you see that the box for 'Update manager' is checked, then it is enabled.

    (Of course, the box for 'Update manager' might be checked, and yet it might not actually be enabled if you check-marked the box recently, and you neglected to click the page bottom button "Install", and, you have not yet navigated away from the 'Extend' page.)

    Refresh the 'Extend' page, and check for the check-mark again. If the box for 'Update manager' is not checked, put a check-mark in the box. Scroll to the bottom of the page, and click the button "Install".

    'Install new module' still not showing after enabling 'Update manager'

    After you are sure that you have enabled 'Update manager', it is quite possible that you may not yet be seeing the button/link "Install new module" at the top of the 'Extend' page.

    I have found that for Drupal 8.3-dev, I must also either 'run the update script', or 'clear all caches' to get get the "Install new module" button/link to show up. ('Clear all caches' is easier) The detailed steps to do those two things are below at Broken site problems - Run the update script, and 'Clear all caches' ⤵.

    Note: 'Clear all caches' is easier, quicker, and does work for me, without my having to 'run the update script'.

    Security: Enable 'Update manager' regardless

       | Contents at this point ⤴ | Skip over this ⤵ | 

    Regardless of whether or not you intend to use one of the automated methods for importing your module, you should always have your Drupal core module 'Update manager' enabled.

    It is important that you are notified when Drupal core updates are available that are 'security updates', so that you can IMMEDIATELY update your site.

    Otherwise, you run the extremely rare but possible risk of having your site hacked into after the Drupal security team releases the details of a Drupal site's vulnerabilities, as they do, if needed, on the third Wednesday of the month between 12 noon and 5pm Eastern time. Security release numbers and release timing explained ~ drupal.org ⎘.

    For all the scary details relating to the most infamous occurrence of this, (known officially as 'Drupageddon', without the 'l', but also commonly known as 'Drupalgeddon', with the 'l') do a Google search for Drupalgeddon 2014-10-15 ~ google.com ⎘.

    During the original browser-based creation of your Drupal 8 site, the check-box for 'Update notifications': "Check for updates automatically" may not have been left selected.

    Or, you may have un-installed the 'Update manager', because you do not want to see daily notices in your email about your Drupal site having updates available.

    Set it to weekly, if that is the case, by going to [d8-root]/admin/reports/updates/settings, which you can get to by going to "Manage" > "Reports" > "Available updates" > click the sub-tab "Settings". On the configuration page, select the radio-button for 'weekly', instead of the default option 'daily'.

    For more information about what the core module 'Update manager' can do, see the drupal.org page Update manager (and Update status) ⎘.

    Module import - The steps

       | Contents at this point ⤴ | 

    These are the actual steps for importing a module using the three different methods.

    As recommended above, at this point, you should have the Drupal core module 'Update manager' module enabled, and you should be seeing, "Install new module" at the top of the 'Modules' page. That is, in fact, required for the two 'automated' module import methods discussed below.

    Also, as mentioned above, the first two 'automated' methods for importing a module, in some rare cases, are not permitted by some servers, and so the third method, 'manually' importing your module, will be required instead.

    I have never experienced that 'server' problem, but I can not imagine that the problem relates to a 'local' Drupal installation. I have never had that problem on my $8-USD per month 'Drupal friendly' shared webhost account I found 5-years ago at Drupal Shared Hosting ~ drupal.org/hosting [$3-USD per month for 3-years if pre-paid on new accounts only] ⎘, so I presume that the problem relates only to 'shared' webhosting accounts at sub-standard companies.

    Automated module import with URL - The steps

       | Contents at this point ⤴ | 

    This is the easiest method to use, and is what I do every time I am checking out a new module (or theme). It works for 'local' Drupal sites running on your computer, and for 'online' sites at a webhost.

    This automated import process will extract all of the module's files and folders into your codebase at [d8-root]/modules/*NEW-SINGLE-MODULE-FOLDER-HERE*

    [Themes: [d8-root]/themes/*NEW_THEME_HERE--A_SINGLE_FOLDER*/*MULTIPLE_THEME_FILES_AND_FOLDERS_HERE*]

    This 'automated' method requires you to have the Drupal core module 'Update manager' enabled. Jump up to Enable the Drupal core module 'Update manager'. ⤴

    Go to 'Extend' page.

    Go to your 'Extend' page, and near the page-top, just under the word 'Extend', you should see the button/link "Install new module".

    Drupal 8 website 'Modules' page 'Install new module' button for importing a new module

    If you do not see the button/link "Install new module" at the top of the 'Modules' page, return above to this page's section Enable the Drupal core module 'Update manager' ⤴ and carefully follow all of the steps outlined there.

    Click "Install new module".

    The page you are taken to does not have a title, but the address is [d8-root]/admin/modules/install

    Go to your module's drupal.org project page, and 'Copy' the module's download link

    Return to the project page for the module you want to install, and scroll down to the 'Downloads' section.

    If you need help deciding which version to use, jump up to the section Understand the various module versions available ⤴.

    In the 'Download' column, RIGHT-click the text-link for either the *.tar.gz file, or the *.zip file. (Windows: use *.zip)

    In the drop-down 'context menu' that appears, if you use:

    Return to your site

    Drupal Update manager page snippet for installing a module

    Paste the URL, which you have 'copied', into the box for: 'Install from a URL'.

    [Ctrl]+[V] - I prefer to do my 'pasting' by clicking once inside the box, so that the cursor is flashing on the left. Then I hold down one of my two "Ctrl" (Control) keyboard keys, and then I press the key "V". (The MAC 'Command' key = my Windows 'Ctrl' key)

    Click the button/link "Install".

    This automated import process will extract all of the module's files and folders into your codebase at [d8-root]/modules/*NEW-SINGLE-MODULE-FOLDER-HERE*

    [Themes: [d8-root]/themes/*NEW-SINGLE-THEME-FOLDER-HERE*]

    If your site asks for your FTP username and password

     | Jump over this. ⤵ | 

       {{COMMENT: I am not sure how any of the two following paragraphs might apply, because it was posted by someone else. I will say that FTP, per se, is Not secure, and that instead you should figure out how to use SFTP (Secure File Transfer Protocol.}}

    If your site asks for your FTP username and password, it is referring to the username and password that you use to access your online webhosting account. If you have multiple sets of login credentials, use the set that you use to access your 'Control panel', as opposed to the set for your account finances.

    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, and will only tell you that there is one. It's up to you to determine whether your server is properly configured for FTP.

    "Installation was completed successfully."

    On the next page that loads, you will see "Installation was completed successfully."

    Click the link "Enable newly added modules" to return to the Drupal 8 'Extend' page.

    [Themes: Click the link "Enable newly added themes", and you will be taken to your site's 'Appearance' page]

    Not that I am recommending it, but if you want your module moved from its current location at [d8-root]/modules/*NEW-SINGLE-MODULE-FOLDER-HERE* into a sub-folder, as for example into

    [d8-root]/modules/contrib/*NEW-SINGLE-MODULE-FOLDER-HERE*

    now is the ideal time to do it, before you start using it, as was discussed above at Using sub-folders of the 'modules' folder ⤴.

    Although I recommend that you read the next two sections that describe the other two methods for importing a module into your site, you can jump over them and continue at the section Enabling modules ⤵.

    Automated module import of local file - The steps

       | Contents at this point ⤴ | 

    This method is used to automatically import a module into a local or an online site from a *.tar.gz or *.zip file on your computer.

    This 'automated' method requires you to have the Drupal core module 'Update manager' enabled. Jump up to Enable the Drupal core module 'Update manager'. ⤴

    This automated import processes will extract all of the module's files and folders into your codebase at
    [d8-root]/modules/*NEW_MODULE_HERE--A_SINGLE_FOLDER*/*MULTIPLE_MODULE_FILES_AND_FOLDERS_HERE*

    [Themes: [d8-root]/themes/*NEW_THEME_HERE--A_SINGLE_FOLDER*/*MULTIPLE_THEME_FILES_AND_FOLDERS_HERE*]

    Go to the 'Extend' page.

    Go to your 'Extend' page, and near the page-top, just under the title 'Extend', you should see the button/link "Install new module".

    [As mentioned above, the 'Install new modules' button/link works just fine for themes as well.]

    Drupal 8 website 'Modules' page 'Install new module' button for importing a new module

    If you do not see the "Install new module" button/link, carefully follow all of the instructions above at Enable 'Update manager' ⤴

    Click "Install new module"

    The page you are taken to does not have a title, but the address is [d8-root]/admin/modules/install

    Download module from project page

    Return to the drupal.org project page for the module you want to install.

    Scroll down to the 'Downloads' section.

    In the 'Download' column, find the version you want to download. If you need help deciding which version to use, jump up to the section Understand the various module versions available ⤴.

    Click the text-link for either the *.tar.gz file, or the *.zip file (Windows: use *.zip)

    Typically, that will start the download of the file.

    If you need help controlling exactly where downloads are saved onto your computer, see this section on a different drupal.org page: Know your browser's file-download location; or change browser's download location. ~ drupal.org/1248034#dl_location ⎘.

    Return to your site page 'Extend'

    Drupal Update manager page snippet for installing a module

    Under the heading 'Upload a module or theme archive to install', click the button "Browse".

    Navigate on your computer to the location of the *.tar.gz or *.zip module file you downloaded.

    Click the button/link "Install".

    This automated import process will extract all of the files and folders from the archived/compressed *.tar.gz or *.zip file into your codebase at [d8-root]/modules/*NEW-SINGLE-MODULE-FOLDER-HERE*

    [Themes: [d8-root]/themes/*NEW-SINGLE-THEME-FOLDER-HERE*]

    If your site asks for your FTP username and password

     | Jump over this. ⤵ | 

       {{COMMENT: I am not sure how any of the two following paragraphs might apply, because it was posted by someone else. I will say that FTP, per se, is Not secure, and that instead you should figure out how to use SFTP (Secure File Transfer Protocol.}}

    If your site asks for your FTP username and password, it is referring to the username and password that you use to access your online webhosting account. If you have multiple sets of login credentials, use the set that you use to access your 'Control panel', as opposed to the set for your account finances.

    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, and will only tell you that there is one. It's up to you to determine whether your server is properly configured for FTP.

    "Installation was completed successfully."

    On the next page that loads, you will see "Installation was completed successfully."

    Click the link "Enable newly added modules" to return to the Drupal 7 'Modules' page.

    [Themes: Click the link "Enable newly added themes", and you will be taken to your site's 'Appearance' page.]

    Not that I am recommending it, but if you want your module moved from its current location at...

    [d7-root]/sites/all/modules/*NEW-SINGLE-MODULE-FOLDER-HERE*

    ...into a sub-folder of the 'modules', as for example, into a sub-folder named 'contrib', at...

    [d8-root]/modules/contrib/*NEW-SINGLE-MODULE-FOLDER-HERE*

    ...then now is the ideal time to do it, before you start using it, as was discussed above at Using sub-folders of the 'modules' folder ⤴.

    Although I recommend that you read the next section that describes the third method for importing a module into your site, you can jump over it and continue at the section Enabling modules ⤵.

    Manual module import - The steps

       | Contents at this point ⤴ | 

    With this method of importing a module, you manually put the module where it belongs into your 'local' or 'online' codebase. You will also have to extract the module's files and folders from the module's *.tar.gz or *.zip file either before or after the move to the codebase.

    Download module from project page

    Return to the project page for the module you want to install.

    Scroll down to the 'Downloads' section.

    In the 'Download' column, find the version you want to download. If you need help deciding which version to use, jump up to the section Understand the various module versions available ⤴.

    Click the text-link for either the *.tar.gz file, or the *.zip file (Windows: use *.zip)

    Typically, that will start the download of the file.

    If you need help controlling exactly where downloads are saved onto your computer, see this section on a different drupal.org page: Know your browser's file-download location; or change browser's download location. ~ drupal.org/1248034#dl_location ⎘.

    Local

    If your site is running locally on your computer, paste the downloaded file at [d8-root]/modules/*HERE*.

    Note: For more information on working with *.tar.gz and *.zip files, including where to get free programs to create them on Linux, MAC, and Windows, see the drupal.org page mentioned above at its heading: *.tar.gz versus *.zip ⎘

    Local

    If your site is running locally on your computer, paste the downloaded file at [d8-root]/modules/*HERE*.

    [Themes: [d8-root]/themes/*HERE*]

    Extract the file's contents into that folder by doing the following.

    For Windows, to extract the contents of the *tar.gz or *.zip file, RIGHT-click on the file, and in the drop-down context menu, click "Extract here" to use the built-in Windows extractor. Or better yet, use a program like 7-zip ~ 7-zip.org ⎘.

    On modern Mac systems, double-click the .tar.gz file.

    Check the structure of the folders after a manual extraction to make sure that the module's folders are in the proper place, and are structured properly. This will be discussed in more detail in the next section Check file/folder structure after manual extraction ⤵

    You can now delete the *.tar.gz or *.zip file if you like.

    Online

    If your site is 'online', upload the file using your webhost Control Panel, or use SFTP (secure file transfer protocol). I highly recommend against using FTP because it is not secure.

    Put the *.tar.gz or *.zip file at [d8-root]/modules/*HERE*.

    [Themes: [d8-root]/themes/*HERE*]

    You can then extract the *.tar.gz or *.zip file using your webhost Control Panel 'File Manager'. Navigate to the file, highlight it, and then click the page-top button "Extract".

    Or, to extract it after it is online, your SFTP program might have a feature for accomplishing that task.

    You can now delete the *.tar.gz or *.zip file from your website, if you like.

    Check file/folder structure after manual extraction

     | Contents at this point ⤴ | Jump over this. ⤵ | 

    You should examine the files and folders structure of your module after you perform a manual extraction to make sure that everything is in its proper place.

    This is not something you have to do after using one of the two automated import processes, but is something you should do after you manually extract a *.tar.gz or *.zip file on your computer, or online.

    The problem lies in the possibility of the module's parent folder being created twice: Once as a parent folder, and again as a child of that parent, with both folders having the same name.

    The possibility of that problem is not limited to, but is common when, for example, you are dealing with *.tar.gz files on a Windows computer.

    Using, for example, the module 'Token', what you do Not want to have is a parent and its child both named 'token', like this:

    [d8-root]/modules/token/token/*MULTIPLE_MODULE_FILES_AND_FOLDERS_HERE*

    If you see that situation, eliminate one of the two identically named module folders by moving all of the *MULTIPLE_MODULE_FILES_AND_FOLDERS* up one level, so that you get this (again, using the 'token' module as an example):

    [d8-root]/modules/token/*MULTIPLE_MODULE_FILES_AND_FOLDERS_HERE*

    [Themes: Similarly, using the theme 'Bootstrap' as an example, you do Not want to have multiple 'bootstrap' folders inside of each other, and so if you see the following, it is a problem: [d8-root]/themes/bootstrap/bootstrap/*MULTIPLE_THEME_FILES_AND_FOLDERS_HERE*]

    1. Login to your webhost Control Panel.
    2. Go to "Files" > "File manager".
    3. Navigate to the *.tar.gz or *.zip file.
    4. Click on the file once to highlight it.
    5. Click the page-top button "Extract".
  6. Enabling modules

    After a module has been imported, it is only taking up space. It is not actively using any of your sites resources except storage space. Only after you enable it does it become active, and if you disable it, it again returns to a dormant state, just taking up space, but no longer affecting your site.

    To enable your new module, go to your site's 'Extend' page.

    [Themes: To enable your newly added theme, you will need to go to your 'Appearance' page. See above at

     | 'Appearance' page overview ⤴

    'Appearance' page overview ⎘  for an overview of your site's Appearance page, including information on the possibility of using two different themes on your site at the same time-- one theme for the site in general, and another theme for 'admin' pages only. Please note also that the official, though currently incomplete, page for installing D8 themes is Installing themes ⎘  (This link opens in a new tab/window.) The following two sections on this page relate to 'enabling' and 'configuring' modules, both 'core' and 'contrib' modules, including module 'permissions' information. If that does not seem to interest you, you might, never-the-less, before leaving this page, be interested in the information below: Broken site problems - Run the update script, and 'Clear all caches' ⤵, or Module documentation and help ⤵, which apply equally to D7 and D8 for fixing site problems, and for researching anything Drupal related.]

    Module enabling: In a hurry? If you put a check-mark in the box for a module on the 'Extend' page, and scroll to the page bottom and click the button "Install", you will enable that module.

    'Extend' page overview (part 1)

       | Contents at this point ⤴ | 

    On the 'Extend' page, every module that exists in your codebase had a row of its own in the tabular list.

    The top of the table does not have names for the columns.

    Check-box column

    The first column on the left is for check-boxes.

    When the check-box is not checked, it means the module is not enabled. If you were to check it, and scroll to the bottom of the page, and click the button "Install", that would 'enable' that module.

    When the check-box is checked, it means that the module is enabled, and therefore 'working' on your site.

    Name column

    To the right of the check-boxes is the module's 'human readable' name.

    Description column (part 1)

    The third column is for 'descriptions'.

    If you 'are' seeing descriptions to the right of each module name, then you can skip over the next section, which is the 'fix' for those who do not see them.

    The following 'fix' section does include an overview of the 'Appearance' page for themes, however, in case you are interested.

     | Skip the 'Fix', & jump down to 'Extend' page overview (continued [part 2]) ⤵. | 

    Fix: Show hidden module descriptions on 'Extend' page

       | Contents at this point ⤴ | Jump over "Fix:..." to "'Extend' page overview (continued [part 2])". ⤵ | 

    If you are not seeing the column with the module descriptions to the right of the column with the module names, but rather, you are only seeing the column of check-boxes and module names to the right, then your browser window is too narrow for whichever 'responsive' theme you are currently using for the administration pages of your site.

    In other words, your responsive 'Administration theme' is hiding the descriptions because your browser is too narrow to display them within the browse window.

    To correct this situation, start by closing the vertical left-hand administration menu, if you have it open, by clicking the admin-menu item "Manage".

    If you are still not seeing the description for each module to the right of its name, then do the following, notably the third item, set your admin theme to 'Stark'.

    Use a larger browser window

    Make your browser window larger. If that does not work, or, if that is not possible because, for example, you are on a mobile device...

    Use smaller font

    Try making the font as small as you can, and yet still usable.

    Core theme Stark for 'Administration theme'

       | Contents at this point ⤴ | 

    If the descriptions still do not show up, you can go the themes' 'Appearance' page, and set the theme 'Stark' as your 'Administration theme'.

    The table on the 'Extend' page will no longer be 'responsive', but rather, it's rows will extend off the sides of your screen.

    You will have to scroll left-to-right, side-to-side, but at lest you should be able to see the module descriptions for a change.

    'Appearance' page overview

     | Contents at this point ⤴ | Skip "'Appearance' page overview", and jump to "Install Stark and set as 'Administration theme'" ⤵ | 

    The 'Stark' theme comes with Drupal core, and will reveal the 'descriptions' column, though you will have to scroll horizontally (left - right) to view those descriptions.

    Go to the 'Appearance' page, and find the theme 'Stark'.

    It will quite possibly be in the section 'Uninstalled theme'. That section is closer to the bottom of the page, under the section 'Installed themes'. By default, Stark is not enabled upon the creation of a Drupal 8 site.

    'Install' versus 'Install and set as default'

    The administrative (admin) pages of your site, by default, use a different theme than your non-admin pages.

    'Bartik' is the default theme for non-admin pages, but whichever theme you see at the top of the 'Appearance' page is the theme that is currently being used for your non-admin pages.

    'Seven' is the default theme for admin pages, but you want to set Stark as the admin theme so that is is used on the admin page 'Extend'.

    Before you can set Stark as your admin theme, it has to be enabled ('Install'-ed).

    Under the image and name for 'Stark 8...', you will see the text-links 'Install', and 'Install and set as default' (or, possibly, those links could be on the right).

    If you were to click 'Install and set as default' for Stark, that would enable it, but that would also set Stark as the theme for your non-admin pages, and that is something that you may not want to have happen. Additionally, clicking 'Install and set as default' does Not immediately set Stark as the admin theme, so, I recommend "Install".

    If you click 'Install' for Stark, it will become enabled, and after that you can set it as your admin theme, instead of using 'Seven', or whichever theme you are currently using that is not allowing you to see the descriptions on the 'Extend' page.

    Install Stark and set as 'Administration theme'

       | Contents at this point ⤴ | 

    So, click 'Install' for Stark (unless you want to check out Stark as the theme for non-admin pages, in which case, click 'Install and set as default'.)

    After the 'Appearance' page reloads, scroll down to the very bottom of the page, to the section 'ADMINISTRATION THEME'.

    Tip: By clicking on "ADMINISTRATION THEME", repeatedly, you will toggle what is known as the 'accordion' feature for this item. Specifically, that section will toggle between being 'expanded' and being 'collapsed'.

    Under the sub-heading 'Administration theme', click the downward pointing arrow on the right, to display the list of enabled themes.

    Note aside: The list item 'Default theme' means that the admin theme to be used should simply be whatever theme is currently being used as the 'Default theme' for the non-admin pages. So, whatever theme is currently at the top of the Appearance page will be used as the admin theme as well. And if you change the default theme for the non-admin pages at the top of the appearance page, then that 'front-end' non-admin theme will be used as the administration theme also, from that point forward.

    In the drop-down menu for the 'Administration theme', click on 'Stark', so that it displays in the textarea box.

    Click the page-bottom button "Save configuration".

    Return to the your 'Extend' page.

    'Extend' page overview (continued)

       | Contents at this point ⤴ | 

    On the 'Extend' page, to the right of each module name is the first line of that module's description.

    'Accordion' toggle: By clicking on that first line of the description, repeatedly, you will toggle what is known as the 'accordion' feature for the module descriptions. Specifically, the descriptions will toggle between being 'expanded' and being 'collapsed'.

    Click the top line of the 'description' in the row for the module you installed, to fully expand the description.

    Machine name: The item 'Machine name' will be the same as the name of the parent folder of your module if you are looking at the 'main' module for the module you installed. If the 'Machine name' does not match the folder name of your module, then you are looking a module that is not the main module, but rather, is possibly one of the other modules of a set of multiple modules that came as a set when you installed your module.

    Requires: If this item exists, it will list all of the modules that your module depends on.

    Those other listed modules will need to exist on your site, and be enabled for your module to work.

    Following each module in that listing, you will see either see nothing, or you will see '(disabled)', or '(missing)'.

    'Nothing' is good. That means that the module that your module requires, is already on your site and enabled.

    '(disabled)' means the other module is on your site, but it is not enabled. You do not have to bother with enabling any '(disabled)' module, because when you try to enable your module, you will be prompted to let the Drupal system enable the '(disabled)' module for you.

    '(missing)' means that the other module is not on your site (assuming it is a 'module' that is missing, and not something else, like a 'library'), and you will have to go that module's project page at Drupal to get it.

    One quick way to get to its drupal.org project page is to copy the name as it is listed following 'Requires', and paste that name at the end of the URL:

    https://www.drupal.org/project/

    For example, I have the module 'Paragraphs' as my chosen new module, and its description displays:

    Requires: Entity_reference_revisions (missing)

    So, into my browser address-bar, I put:

    https://www.drupal.org/project/Entity_reference_revisions (...Do not worry about the 'e' being an upper-case 'E')

    ...and I press the keyboard key [Return/Enter].

    Later, after I have entity_reference_revisions installed, the description for Paragraphs displays...

    Requires: Entity Reference Revisions (disabled)

    ...which is a nice change, referring to the name change from 'entity_reference_revisions' to 'Entity Reference Revisions', since 'Entity Reference Revisions' is how that module is listed on the 'Extend' page, and so now I know what specifically to look for in the name column to find 'that' new module.

    Missing libraries and other possible non-module requirements of a module

    At times, a module will be dependent on something besides another module that is missing from your site, as for an example, a library.

    'Required by:' The item 'Required by', when it exists in a module's description is most helpful if, and when, you are considering uninstalling that module, because you can see which other modules, if any, that uninstalling it will affect.

    The 'Required by:' modules that are listed (if any) will be followed by either nothing, or by '(disabled)'. '(disabled)' means it exits on your site, but it is not enabled; whereas if '(disabled)' is not displayed, then that module is both 'on your site' and 'enabled'.

    Multiple modules packaged in one project

    Please Note that it is not unusual for a contrib module to actually be a of set more than one module. Yet, even if a single contrib module project comes with multiple modules, all of the modules from a single download will be found together in a single section on the 'Extend' page.

    If your module came as a set of more than one module, one of them is the main module, and, usually, the other module(s) will be dependent upon the main module to work.

    You will usually want to enable the main module, but you may or may not want to enable the other modules (if any) that came with it.

    The description to the right of the module name (in the tabular list on the 'Extend' page) should give you a good idea of which module is the main one.

    And, as explained earlier, the description will tell you which other modules it is dependent on, if any, and whether or not they already exist on your site, and whether or not they are enabled.

    Do not worry though, because if the module you try to install has another module that it depends upon, and which is either not on your site, or is not enabled, you will get a helpful notice to that effect. If the other module is on your site but not enabled, the notice you will get will also be giving you the option to continue by allowing it to enable that other module for you.

    If, on the other hand, the module you are trying to install is dependent upon another module that is not already on your site, you will have to return to drupal.org, and get that other module from its project page.

    Also, a module might be dependent on something other than another module, as for example, upon a 'library' that needs to be found and downloaded. In that case also, when you try to enable the module, you should get a notice telling you what you are lacking.

    The description for a specific module will also usually list which, if any, of the other modules you have on your site, both enabled and not enabled, that are dependent upon that module.

    If it should happen to be that the module is designed strictly for development purposes, and that it should not be used on a 'live' site for security reasons, or, as another example, because it dramatically slows down the responsiveness of your site, that information would, at a minimum, have been explained on the module's project page, and might also be in the description on the 'Modules' page.

    At the very bottom of the description, the often seen (, but not always,) links 'Help', 'Permissions', and 'Configure' will be displayed if they are available for your module.

    Those items will be discussed individually in the next section, "Configuring modules", after you are done enabling your new module.

    Enable your new module

    Find your new module on the 'Modules' page

    Your new module will never be in the top section 'Core', which is reserved for Drupal 8 modules. Not all of the modules that originally came with Drupal 8 core are in that top section, but the majority are.

    Your module could be in any one of the following sections, but, as to which one, that is dependent on how the module's developer(s) wanted to categorize it.

    Scroll down the page until you find the module you installed.

    Put a check-mark in the left-hand box for any of the modules that you want to enable.

    Click the page-bottom button "Install".

    "Some required modules must be enabled"

    If you happen to be installing a module which 'requires' another module (or several) that are already on your site, but are not enabled, you will get this notice:

    
    
    ____________________________ Some required modules must be enabled You must enable the *REQUIRED-MODULE-NAME-HERE* module to install *YOUR-MODULE-NAME-HERE*. Would you like to continue with the above? ____________________________ 

    That will be followed be a button "Continue", and a text-link "Cancel".

    Click the button "Continue".

    When the 'Extend' page reloads, and displays at the top, "The configuration options have been saved", then you know you have successfully enabled your new module.

    If you would like to double-check that the module is installed, scroll down the module list, and make your new module has a check-mark in its box.