In this tutorial, we'll examine one the first files you'll need in order to create a Drupal module: the info file. Each module is required to have a MODULE.info.yml file to help Drupal identify that a bundle of code is a unique module. This specially-formatted YAML file tells Drupal about the module and provides other useful metadata. In this tutorial, we'll walk through both required and optional information you put in a module's info file.
Goal
Understand what information goes in a module info file. Be able to create an info file that accurately describes your custom module.
Prerequisites
- It helps to know what YAML is, but we'll provide example code that you can copy and paste. See also Introduction to YAML
- You should understand the concept of a module in Drupal. See Concept: Modules (Drupal User Guide)
- You should have a directory created for your custom module in modules/custom/MODULE_NAME where MODULE_NAME is the machine name of your module.
Learn more about naming and placing a module.
- Anatomy of a Module (Module Developer Guide)
- Naming and placing your module (Drupal.org)
Related resource
See also Create an Info File for a Module in our Module Developer Guide.
Contents
Use the following links to jump to a section below:
- Required keys in an info file
- Optional keys in an info file
- Basic example of an info file
- Declaring a dependency on 1 or more modules
- Point to settings form route with configure key
Required keys in an info file
Every Drupal module info file must contain certain keys in order for Drupal to be able to actually install the accompanying module. The required keys for non-core modules are:
-
name
: A name for your module. -
type
: The type of package. For a module info file, specifymodule
. -
core_version_requirement
: The semantic version(s) of core compatible with your module
Source: core/lib/Drupal/Core/Extension/InfoParserDynamic.php (api.drupal.org)
Optional keys in an info file
It can be helpful, or even necessary, to provide the following optional keys in your module:
-
description
: A brief description of its functionality (appears in the module listing on the Extend administrative page) -
package
: Lists the module in a group with value specified. For example, useCustom
to group all your custom modules in a group named "Custom" on the Extend page. -
dependencies
: If applicable, provide a list of dependencies required by the module -
lifecycle
: Specify the stability and maintenance status of your module (see below for example values) -
configure
: Specify the name of the route to the module's configuration form. A link labeled "Configure" will appear in the module listing on the Extend page if a valid route is provided here. -
hidden
: (true) Use if you want to hide your module from the list on Extend. Used most often for modules containing automated tests. To override this setting (and list all hidden modules), add$settings['extension_discovery_scan_tests'] = TRUE
to your site's settings.php. -
php
: Defines the minimal PHP version that is required for your module. Users will not be able to enable the module if they use an older PHP version. This can be used to avoid errors if your module uses newer functions that did not exist in earlier PHP versions. For example,php: 8.0
. -
test_dependencies
: This is used by DrupalCI only. The value is a list of other modules (in the same format as dependencies) that are needed to run certain automated tests for your module on Drupal's automated test runner ("DrupalCI"), but not needed as module dependencies in general. Note that you need to have thetest_dependencies
change committed to your Git repository before you try to run a test that depends on it. As an alternative, you can use Composer for test dependencies. See Dependencies for tests.
Further examples and explanations for these keys are provided below.
Restricted: keys added by Drupal's packaging system
The following keys are added by Drupal's packaging system when "preferred-install": "dist"
is specified in the project's composer.json. Don't add these to your custom module's info file.
-
version
: The version of Drupal. The value is often the global constant,VERSION
. -
project
: The project's shortname, if the module is part of a project hosted in Drupal.org. Used in automated testing, but otherwise ignored by Drupal core.
Basic example of an info file
For a module named hello_world, here is its hello_world.info.yml:
name: Hello World
description: An example module
type: module
core_version_requirement: ^9 || ^10
package: Code examples
Required keys
- name
- type
- core_version_requirement
Optional, but helpful keys
- description
- package
Info file keys
Let's take a closer look at module info file keys.
Declare compatibility with core_version_requirement
The value of core_version_requirement
is a semantic version of one or more versions of Drupal your module requires. If the version doesn't match, the module will not install.
More about core_version_requirement
:
- The
core_version_requirement
key replaced the oldcore
key. - The
core
key is only needed for modules that need to run on sites running Drupal versions less than8.7.7
. - The
core_version_requirement
key was introduced in 8.7.7. - When using the
core_version_requirement
key with anything other thancore_version_requirement: ^8 || ^9 || ^10
, the module should only be tested on Drupal 8.7.7 or later. - The
core
key cannot have a value of10.x
. Use thecore_version_requirement
instead. - For the value of
core_version_requirement
, to use a more granular version requirement than^8 || ^9 || ^10
, remove thecore
key, and specify a semantic version of the Drupal version(s) your module requires withcore_version_requirement
only. (Module will not install otherwise.)
Scenarios and examples: core_version_requirement
Module is compatible with 8.7.7 and above, to the latest minor or patch version of Drupal 8; or, any minor or patch version of Drupal 9 or Drupal 10:
name: Hello World
description: An example module
type: module
core_version_requirement: ^8.7.7 || ^9 || ^10
Module is compatible with any minor or patch version in Drupal 10, starting with 10.1 and above:
name: Hello World
description: An example module
type: module
core_version_requirement: ^10.1
In the previous 2 examples, the core
key is removed, replaced entirely by core_version_requirement
. The module is not compatible with versions of Drupal prior to 8.7.7 in the first example and only version of Drupal 9.1 and higher in the second case.
Why use a more granular core_version_requirement
value?
- If a particular minor or patch release of Drupal contains a bug or security fix that you want to ensure is in place before your module is installed.
- A core feature that your module depends on was introduced within a minor version release cycle.
Convey stability with lifecycle
and lifecycle_link
Introduced in Drupal 9.3.x, you can use the lifecycle
and lifecycle_link
keys to describe the stability of a module (or theme).
Supported values for lifecycle
are as follows:
- experimental: Something new and not finalized. The user receives a warning about its experimental status if you try to install them, but the module works.
-
stable: The default value for
lifecycle
. Stable Drupal extensions with no special warnings or behavior. -
deprecated: Something on the way out in the next major release. You can still install it, but administrator(s) receive warnings if deprecated extensions are installed on the site. (Also provide
lifecyle_link
key with link to documentation or change record.) -
obsolete: Really gone. You should uninstall it. If it's already installed, administrator(s) will see warnings. New installations are prohibited. (Also provide
lifecyle_link
key with link to documentation or change record.)
Note: For deprecated
and obsolete
lifecycle states, a lifecycle_link
key is also required. The lifecycle_link
key should specify a URL to documentation regarding its deprecation or obsolete status. This helps site builders and administrators know what to do with deprecated or obsolete modules installed on their site.
See the change record, Info files can now contain 'lifecycle' and 'lifecycle_link' keys to convey the stability of a module/theme, for more information and examples.
Group modules with the package
key
The package
key is used to group modules. See this in action on the Extend administrative page. Each fieldset heading corresponds to a package
value. If the package
key is not specified, the module will be added to the Other group.
After you install (enable) the module, 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:
package: Custom
Dependencies
If your custom module will require code from other modules, whether core or contributed, they can be listed under the dependencies
key.
When dependencies are listed, Drupal will not allow your module to be installed unless the dependencies can be satisfied. 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:module
, where 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. Use project name drupal
for modules in the core/ directory.
List a core module as a dependency
- Project: Drupal (core)
-
Project URL:
https://www.drupal.org/project/drupal
-
Module machine name(s):
node
- Installed at: core/modules/node
To list the Node module as a dependency for your module, add the following to your module's info file:
dependencies:
- drupal:node
List a contributed module as a dependency
- Project: Webform
-
Project URL:
https://www.drupal.org/project/webform
- Module machine name(s): webform
- Installed at: modules/contrib/webform
To list Webform module as a dependency for your module, in your module's info file, add the following:
dependencies:
- webform:webform
List a module in a project as a dependency
- Project: Devel
-
Project URL:
https://www.drupal.org/project/devel
-
Module machine name(s): main module:
devel
; sub-modules:devel_generate
- Installed at: modules/contrib/devel, modules/contrib/devel/devel_generate
To list Devel Generate, one of the modules contained within Devel, as a dependency for your module:
dependencies:
- devel:devel_generate
You can also define version restrictions on any listing. This will result in a warning on the status report page that a module is incompatible with the core version. (Note: you should probably use the root-level key, core_version_requirement
, to specify core version compatibility with your module instead of drupal:system
under dependencies
.)
Here is an example of what these dependencies would look like in our demo module's "info" file:
name: Hello World
description: An example module
type: module
core_version_requirement: ^8.7.7 || ^9 || ^10
dependencies:
- drupal:node
- webform:webform (>=6.1.0)
- devel:devel_generate
In this case we're telling Drupal that our module cannot be installed unless the core Node module is enabled and the contributed modules Webform and Devel Generate are enabled as well. Also, we're indicating with the core_version_requirement
key that the module is compatible with 8.7.7 and higher, or Drupal 9 or 10.
What about composer.json?
If you're contributing your module back to the community, and you want DrupalCI to test module dependencies for your module, you'll need to list your module's dependencies in a composer.json in the module's root directory, in addition to listing dependencies in the info file. See Add a composer.json file on Drupal.org.
Point to settings form route with configure
key
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's listing on the Extend (admin/modules) page in the extended information about your module. For example, the Search API module uses this value to provide a link to its configuration form.
And the corresponding search_api.info.yml file:
type: module
name: 'Search API'
description: 'Provides a generic framework for modules offering search capabilities.'
package: Search
core_version_requirement: ^10.1 || ^11
lifecycle: stable
configure: search_api.overview
Recap
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's listing on the Extend page. At a minimum a non-core module info file needs to provide the name
, type
and core_version_requirement
keys. The description
and package
keys are recommended as they are used on the Extend page to group and provide information about the module to the user. Additional metadata specifying the dependencies of our module or the route to the configuration form may also be added.
Further your understanding
- Take a look at the MODULE.info.yml files included with core and contributed modules on your site. Are there any additional options this tutorial doesn't cover?
- Use Drush to generate a module. Look at the YAML file it generates. Are there any differences there?
Additional resources
- Let Drupal know about your module with an .info.yml file (Drupal.org)
- Introduction to YAML (Drupalize.Me)
- Develop Drupal Modules Faster with Drush Code Generators (Drupalize.Me)
- 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)
- Change record: info.yml files no longer accept 'core: 9.x' (Drupal.org)
- To check the Drupal 9 readiness of your module, install and run the Upgrade Status module (Drupal.org)
- Add a composer.json file Drupal.org
- Info files can now contain 'lifecycle' and 'lifecycle_link' keys to convey the stability of a module/theme (Drupal.org)