In this tutorial we're going to look at one the first files you will need in order to create a Drupal module: the info file. Each module is required to have a MODULE_NAME.info.yml file to help Drupal identify that a bundle of code is a unique module. This specially-formatted YAML file not only informs Drupal about the module, but also allows us to provide other useful metadata. In this tutorial, we'll walk through all of the metadata possibilities that can be included in an info file.
- Create an info file in YAML format with all of the required metadata for a custom Drupal module.
Every info file must contain certain keys in order for Drupal to be able to actually install the accompanying module. At a minimum you must provide:
- a name for your module
- a brief description of its functionality
- the type (module or theme)
- the major version of core supported by this code
These are the basics you need in place in order to see your module available on Drupal's installation screen. For a module called hello_world, here are the contents of hello_world/hello_world.info.yml
name: Hello World description: A silly example module type: module core: 8.x core_version_requirement: ^8.7.7 || ^9
Notice that our Hello World module has been added to a new group called Other on the module administration page. We can specify a different name for this group for organizational purposes by using the package key in our info file if desired.
New in 8.7.7:
As of Drupal 8.7.7, the new
core_version_requirement key in *.info.yml files for modules and themes now supports Semantic Versioning as implemented by the Composer project. This allows modules and themes to declare which versions of Drupal core they're compatible with and allows for more granular control than the
core key. With
core_version_compatibility, a theme or module can declare major, minor, and patch version compatibility, including compatibility with more than one major version. This means it will be possible for a single release of a module to be compatible with both Drupal 8 and 9. (To check the Drupal 9 readiness of your module, install and run the Upgrade Status module.)
Example 1: Module is compatible with Drupal 8 and 9
For example, a module that is compatible with both Drupal 8 and Drupal 9 would indicate that with the following MODULENAME.info.yml contents:
name: My Module type: module core: 8.x core_version_requirement: ^8 || ^9
core_version_requirement key specifies that the module is compatible with all versions of Drupal 8 and 9. This means that the module would have removed all deprecated code (in order to be compatible with Drupal 9). The
core key is still required here because Drupal core versions before 8.7.7 do not recognize the
core_version_requirement. (Keeping the
core key ensures backward-compatibility of a module with versions of Drupal before 8.7.7.)
Example 2: Module is compatible with 8.8.0 and above, and Drupal 9
In this example, the module is compatible with Drupal 8.8.0 and above as well as Drupal 9:
name: My Module type: module core_version_requirement: ^8.8 || ^9
core key is not used to ensure that versions of Drupal prior to 8.7.7 will not install the module.
Counter example (Don't use this.)
core_version_requirement cannot be used to restrict to core versions before 8.7.7. This is because any version of Drupal prior to 8.7.7 does not recognize the
The following MODULENAME.info.yml would throw a parsing exception:
name: My Module type: module core_version_requirement: ^8.7 || ^9
This is not valid because
^8.7 would include versions like
8.7.0 which do not recognize the
Important note about
It is important when using the new
core_version_requirement key with anything other than
core_version_requirement: ^8 || ^9 that the module be tested on Drupal 8.7.7 or later.
For more information, see the change record and this blog post written by Gabor Hojtsy: Drupal 8.7.7+ will support extensions compatible with both Drupal 8 and 9!.
The YAML info file can also specify dependencies. If our custom Hello World module is going to require code from other modules, whether core or contributed, we can explicitly list them. When dependencies are specified Drupal will not allow your module to be installed unless the dependencies can be satisified. This may be achieved by first installing other available modules, or Drupal may tell you that you need to download another contributed project before your new module can be enabled.
Dependencies should be a list of dependencies with the format
project is the machine name of the project as it appears in its Drupal.org project page URL and
module is the machine name of the module, which can be derived from the directory name that houses the module's code. Many times the project and the module name will be identical, but sometimes a project will contain several modules with distinct functionality. Use project name
drupal for modules in the core/ directory.
Example 1: List a contributed module as a dependency
- Project: Webform
- Project URL: https://www.drupal.org/project/webform
- Module machine name(s):
- Probably installed at: modules/contrib/webform
To list Webform module as a dependency for your module:
dependencies: - webform:webform
Example 2: List a core module as a dependency
- Project: Drupal (core)
- Project URL: https://www.drupal.org/project/drupal
- Module machine name(s): node
- Installation location: core/modules/node
To list Node module as a depdendency for your module:
dependencies: - drupal:node
Example 3: List a sub-module within a contributed project as a dependency
- Project: Devel
- Project URL: https://www.drupal.org/project/devel
- Module machine name(s): main module:
- Probably installed at: modules/contrib/devel, modules/contrib/devel/devel_generate, modules/contrib/devel/kint, modules/contrib/devel/webprofiler
To list Kint as a dependency for your module:
dependencies: - devel:kint
You can also define version restrictions on any listing, or even on Drupal's core system, for example,
drupal:system (>=8.2.0). This will result in a warning on the status report page that a module is incompatible with the core version.
Here is a complete example of what these dependencies would look like in our demo module's "info" file:
name: Hello World description: A silly example module type: module core: 8.x dependencies: - drupal:node - webform:webform - devel:kint - drupal:system (>=8.2.0)
In this case we're telling Drupal that our module can not be installed unless the core Node module is enabled and the contributed modules Webform and Kint (part of Devel) are enabled as well. Also, we're indicating that the module is compatible with Drupal core version 8.2.0 and higher.
The other main key you may find in info files is configure. Use this only if your module needs to provide particular configuration settings that are exposed to the site administrators. The
configure key in your module's info file specifies the route that will be used to navigate to the module's configuration settings form. A link to this configuration form will automatically be added to the module administration Extend page in the extended information about your module. For example, the REST UI module uses this value to provide a link to its configuration form.
And the corresponding restui.info.yml file:
name: REST UI type: module description: "Provides a user interface to manage REST resources" package: Web services core: 8.x configure: restui.list dependencies: - drupal:rest - drupal:system (>=8.2.0)
If you look at other info YAML files, especially from contributed modules you might notice additional key/value pairs. In particular, Drupal.org's packaging script adds information about the specific version and a datestamp for when that module was generated. None of this metadata is required in a custom module you develop, but can be useful when troubleshooting during development.
In this tutorial, we looked at the main elements that make up info files for Drupal modules. This type of file is required in order for Drupal to recognize our code as a module, and to get it to show up on the module administration's Extend page. At a minimum our info file needs to provide the name, description, type and core compatibility keys. Additional metadata specifying the dependencies of our module, the route to the configuration form may also be added.
Further your understanding
- Take a look at the info.yml files included with core and contributed modules on your site. Are there any additional options this tutorial doesn't cover?
- Use Drupal Console to generate a module. Look at the YAML file it generates. Are there any differences there?
- Try writing a info.yml file for one of your existing modules (without looking at the documentation). Did you get all of the dependencies correct?
- Introduction to YAML (Drupalize.Me)
- Drupal Console (Drupalize.Me)
- Let Drupal 8 know about your module with an .info.yml file (Drupal.org)
- Module version dependency in .info.yml is ineffective for patch releases (Drupal.org)
- Semantic Versioning (Drupalize.Me)
- Change record: New 'core_version_requirement' key in info.yml files for modules and themes allows Composer semantic version constraints including specifying multiple major versions of core (Drupal.org)
- Drupal 8.7.7+ will support extensions compatible with both Drupal 8 and 9! (hojtsy.hu)