Naming and placing your Drupal module

Before You Begin

If you want PHP to help identify your errors on a test site, try the settings described here: Displaying all errors during development.

Name Your Module

The first step in creating a module is to choose a “short name” or machine name for it. This machine name will be used in several files and functions of your module, and the Drupal core uses it programmatically to reference your module.

There are several important rules to follow when choosing a machine name:

• It must start with a letter.
• It must contain only lowercase letters and underscores.
• It must not contain spaces.
• It must be unique. Your module should not have the same short name as any other module, theme, or installation profile that you will use on the site.
• It must not include any reserved terms: src, lib, vendor, assets, css, files, images, js, misc, templates, includes, fixtures, Drupal

For this case, we will choose "hello_world" as the machine name.

Important note: Do not use uppercase letters in your module’s machine name, as Drupal will not recognize your hook implementations. See Understanding the Drupal module hook system.

Create a Folder for Your Module

Given that we chose the machine name "hello_world", start the module by creating a folder in your Drupal installation at the path: /modules/custom/hello_world or /sites/all/modules/hello_world. You may omit the /custom subfolder and place your module in /modules/hello_world instead, but it is often a good idea to have a dedicated place for your own modules so you don’t have to search through those downloaded from drupal.org.

Note that it is not necessary to use the same name for your module folder as the machine name. Instead, you can use a folder name like HelloWorld. However, you must remember to use the machine name programmatically in your module's code and file names.

Previous versions of Drupal required custom modules to be located in /sites/all/modules, since core modules were located in /modules. However, in Drupal 8, /modules is now open for your custom and contributed modules. All core modules and library files are now located in the /core directory. In Drupal 8, you can still follow Drupal 7/6 best practices of placing your custom and contributed (downloaded) modules in /sites/all/modules, but you can also simply place them in the /modules directory, which has the same effect.

Our example module does not work yet — we will first need a .info.yml file. Learn more about informing Drupal 8 about your module using a .info.yml file. We will activate the module later in the guide.

Coding Standards

We strongly recommend that you follow Drupal's coding standards when writing your own custom modules. This is a requirement for any proposed changes to Drupal core code, and also a recommendation for code hosted on drupal.org.

See Also

• Displaying all errors during development
• Coding standards