On this page
- Hello World
- Specifying core_version_requirement
- Specifying the core_version_requirement
- Complete example
- Version restrictions for dependencies
- Debugging .info.yml files
- Module is not listed on admin/modules page
- Module is listed on admin/modules but its checkbox is disabled.
- Module description is empty
- Adding a composer.json file
- See also
Let Drupal know about your module with an .info.yml file
This documentation needs review. See "Help improve this page" in the sidebar.
Main topic described: project metadata
A .info.yml
file (aka. "info yaml file") is an essential part of a Drupal 8+ module, theme, or install profile to store metadata about the project.
These .info.yml
files are required to:
- Notify Drupal about the existence of a module, theme, or install profile.
- Specify if this is a theme, or module.
- Provide information for the Drupal Web UI administration pages.
- Provide criteria to control module activation and deactivation and Drupal version compatibility.
- General administrative purposes in other contexts.
For more information see the latest API documentation for InfoParserInterface::parse.
Hello World
The following is the hello_world.info.yml
file we will be using. If you are following along, go ahead and create a new hello_world.info.yml
file in your module's root folder, and paste this code into it.
name: Hello World Module
description: Creates a page showing "Hello World".
package: Custom
type: module
core_version_requirement: ^9.4 || ^10
Let's take a look at each line to see what it does.
The first three lines are primarily used in the administration UI when allowing users to enable or disable your module. The name
and description
keys provide the text that is shown on the module administration page.
The package
key allows you to group like modules together. Core, for example, uses package: Core
to group all of the modules provided with Drupal core together, likewise you might use package: Custom
to group all of your projects custom modules together making them easier to locate and enable. package
entries should follow Drupal capitalization standard and use sentence case ("User interface" not "User Interface") by default, except if referring to something which properly uses title case ("Organic Groups").
The type
key, which was introduced in Drupal 8, indicates the type of extension, e.g. module, theme, or profile.
For modules hosted on drupal.org, the version number will be filled in by the packaging script. You should not specify it manually, but leave out the version line entirely.
The core_version_requirement
key specifies with which Drupal core versions your module is compatible.
name
, type
and core_version_requirement
are required keys.
Specifying core_version_requirement
Warning
At this time, DrupalCI does not support testing patches which change the core_version_requirement.
When determining core version constraints, the following order of precedence is used.
- If a core requirement is specified in
composer.json
, it receives utmost precedence. - If there is no core requirement in
composer.json
, the core_version_requirement ininfo.yml
will take precedence next. - If the core_version_requirement is not set in
info.yml
, then any version specified on a core module in theinfo.yml
dependencies section will be used.
Specifying the core_version_requirement
The core_version_requirement
key in *.info.yml
files for modules, themes, and profiles now supports semantic versioning as implemented by the Composer project. This allows modules, themes, and profiles to also specify that they are compatible with multiple major versions of Drupal core.
For example, a module that is compatible with Drupal 9 and Drupal 10 can have a info.yml
file like this
name: My Module
type: module
core_version_requirement: ^9 || ^10
For example a module that is compatible with Drupal 8 and Drupal 9 can have a info.yml
file like this
name: My Module
type: module
core: 8.x
core_version_requirement: ^8 || ^9
This specifies that the module is compatible with all versions of Drupal 8 and 9. The core:
is required here because Drupal Core versions before 8.7.7 do not recognize the core_version_requirement:
key.
Most modules however will have to remove deprecated code to be compatible with Drupal 9. Therefore they will not able to be compatible with all versions of Drupal 8.
For example a module that is compatible with Drupal 8 versions after Drupal 8.8.0 and also Drupal 9 will need a info.yml file like this:
name: My Module
type: module
core_version_requirement: ^8.8 || ^9
The core:
key must not be used here to make sure that versions of Drupal before 8.7.7 will not install the module. Adding both core
and core_version_requirement
with anything other than core_version_requirement: ^8 || ^9
will result in an exception.
The core_version_requirement
cannot be used to restrict to core version before 8.7.7. For instance, core_version_requirement: ^8.7 || ^9
would throw a parsing exception: This is not valid because ^8.7
would include versions like 8.7.0 which do not recognize the core_version_requirement:
key.
When using the new core_version_requirement
key with anything other than core_version_requirement: ^8 || ^9
, it is important that the module be tested on Drupal 8.7.7 or later.
Complete example
In addition to the basic properties shown in the previous example, there are also a number of optional properties. This is a complete example.
name: Hello World Module
description: Creates a page showing "Hello World".
package: Custom
type: module
core_version_requirement: ^9.4 || ^10
dependencies:
- drupal:link
- drupal:views
- paragraphs:paragraphs
- webform:webform (>=6.1.0)
test_dependencies:
- drupal:image
configure: hello_world.settings
configure_parameters:
pluginId: hello_world_plugin
php: 8.0
hidden: true
required: true
# Set the module lifecycle status deprecated
lifecycle: deprecated
lifecycle_link: https://www.drupal.org/node/3223395#s-aggregator
# Note: do not add the 'version' or 'project' properties yourself.
# They will be added automatically by the packager on drupal.org.
# version: 1.0
# project: 'hello_world'
dependencies
: a list of other modules your module depends on. Dependencies on Drupal core or contrib modules should be namespaced in the format{project}:{module}
, where{project}
is the project name as it appears in the Drupal.org URL (e.g. drupal.org/project/paragraphs) and{module}
is the module's machine name. Dependencies can also include version restrictions, for examplewebform:webform (>=6.1.0)
(see below). Note that if your module has dependencies on other contributed modules or libraries, these should be declared in the module's composer.json file. If you have local custom modules that are dependent on each other you can use{module}:{module}
(or{module}:{submodule}
for sub-modules.)test_dependencies
: a list of other modules (in the same format asdependencies
) 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 (or that are in development as module dependencies but not finalized yet). Note that you need to have the test_dependencies change committed to your Git repository before you try to run a test that depends on it – you cannot just put the info.yml change into the same patch as the new test. As an alternative, you can also use Composer for test dependencies – see the relevant documentation for more information.configure
: if your module offers a configuration form, then you can specify the route to this form here. It will then show up as a link in the Extend page (at /admin/modules URL path) when the user expands the details.configure_parameters
: if a route for a configuration form requires parameters, you can set them here.php: 8.0
: 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.hidden: true
: this will hide your module from the module list on the Extend page. You might find it useful to hide a module if it only contains tests, or is intended to serve as an example for developers who need to implement the main module's API. You can make these modules visible by adding$settings['extension_discovery_scan_tests'] = TRUE
to your settings.php file.required: true
: this means your module must be enabled and cannot be uninstalled.-
lifecycle: deprecated
lifecycle_link: https://www.drupal.org/node/3223395#s-aggregator
The combination oflifecycle: deprecated
and lifecycle_link marks a module deprecated and explains the deprecation in the lifecycle_link. (This example is from the aggregator module.) - Restricted properties, added by Drupal packaging system (only when
"preferred-install": "dist"
is set in project'scomposer.json
). Do not add these manually to info.yml in your repository.version
project
Version restrictions for dependencies
Dependencies can also include version restrictions, for examplewebform:webform (>=6.1.0)
.
These restrictions do not follow the same rules as compoyer.json version restrictions, but are Drupal's own invention.
To understand what is possible, see \Drupal\Component\Version\Constraint
and \Drupal\Core\Extension\Dependency::isCompatible
.
You can also find the Drupal 7 docs for this here.
Debugging .info.yml files
Module is not listed on admin/modules
page
- Ensure the info file is named
{machine_name}.info.yml
and is located in the root of the module's directory. - Ensure the file is formatted correctly. For example, there cannot be spaces before but must be a space after the colon (
:
) sign. Formatting should look like as seen in the next example. - Ensure that the file has this line:
type: module
- Ensure the module name starts either with a letter or an underscore. The following is an excerpt from the PHP documentation about valid function names.
Function names follow the same rules as other labels in PHP. A valid function name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thus:
[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*
.
Module is listed on admin/modules
but its checkbox is disabled.
- Make sure that the core compatibility is set to be compatible with your version of Drupal.
core_version_requirement: ^9.4 || ^10
- Ensure that all the module dependencies are available. You can expand the module information to see which requirements are missing.
Note that some modules have been moved out of Drupal 8 core, whereas other contributed modules have been moved into core or replaced by new core modules.
Module description is empty
- Remember that the value of
description
is used for the description.
description: Example Module description.
Adding a composer.json file
In addition to declaring dependencies on other modules in the .info.yml
file, if a contributed module on Drupal.org wishes to test changes to module dependencies using DrupalCI as part of development, they must have a composer.json that expresses those Drupal module dependencies (DrupalCI can only detect changes to dependencies in patches within composer.json
, not in .info
or .info.yml
files).
See also
- YAML
- .info to .info.yml change notice
- API documentation for
InfoParser::parse()
- Drupal 7 modules .info files
- Drupal 6 modules .info files
- Defining a theme with a .info.yml file
- Converting Drupal 7 modules to Drupal 8 Step 1: Convert mymodule.info to mymodule.info.yml
- Modules can no longer add stylesheets/scripts via their .info.yml file change record
- Add a composer.json
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion