Mention Drupal about your module using .info.yml file

14/04/2025, by Ivan

Main Topic: Project Metadata

The .info.yml file (also known as the "info YAML file") is an essential part of a Drupal 8 module, theme, or installation profile used to store metadata about the project.

These .info.yml files are required to:

Inform Drupal about the existence of a module, theme, or installation profile.
Distinguish between themes and modules by type.
Provide information for Drupal Web UI administration pages.
Specify criteria for managing module activation/deactivation and compatibility with Drupal versions.
Serve general administrative purposes in other contexts.

For more information, see the latest API for InfoParserInterface.php. (Click View Source.)

Hello World

Below is the hello_world.info.yml file we will use. If you're following along, 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: 8.x

Let’s look at each line to understand what it does.

The first three lines are mainly used in the admin UI when users enable or disable your module. The name and description keys provide the text displayed on the module administration page, and the package key allows grouping similar modules together. For example, Core uses package: Core to group all core Drupal 8 modules; you can use package: Custom to group your custom project modules, making them easier to find and enable.

The type key, new in Drupal 8, indicates the type of extension: module, theme, or profile.

For modules hosted on drupal.org, the version number will be added by the packaging script. You should not specify this manually and should omit the version line entirely.

The core key specifies which version of Drupal core your module is compatible with.

name, type, and core are required keys.

Specifying core_version_requirement
Warning: Currently, DrupalCI does not support test patches that change the core_version_requirement.

Do You Need core_version_requirement?

The following priority order is used when determining core version constraints:

If specified in composer.json, it takes highest priority.
If not specified in composer.json, core_version_requirement in info.yml takes precedence.
If core_version_requirement is not set, the version specified under dependencies in the main module's info.yml will be used.

Specifying core_version_requirement When Necessary

The new core_version_requirement key in *.info.yml files now supports semantic versioning, implemented by the Composer project. This allows modules, themes, and profiles to specify compatibility with multiple major versions of Drupal core.

For example, a module compatible with both Drupal 8 and 9 might use:

name: My Module
type: module
core: 8.x
core_version_requirement: ^8 || ^9

This indicates the module is compatible with all versions of Drupal 8 and 9. The core key is required because Drupal Core versions prior to 8.7.7 do not recognize core_version_requirement.

However, most modules will need to remove deprecated code to be Drupal 9-compatible, meaning they may not be compatible with all Drupal 8 versions.

For example, a module compatible with Drupal 8.8.0+ and Drupal 9 would require:

name: My Module
type: module
core_version_requirement: ^8.8 || ^9

The core key should not be used here to prevent installation on versions before 8.7.7. Including both core and core_version_requirement with values other than ^8 || ^9 will trigger an exception.

core_version_requirement cannot be used to limit core versions to pre-8.7.7 releases. For instance, ^8.7 || ^9 would include 8.7.0, which doesn't support the key and will trigger a parse exception.

This is important when using any value other than ^8 || ^9; your module must be tested on Drupal 8.7.7 or later.

Full Example

In addition to the core properties shown earlier, several additional properties are available. Here's a complete example:

name: Hello World Module
description: Creates a page showing "Hello World".
package: Custom

type: module
core: 8.x

dependencies:
  - drupal:link
  - drupal:views
  - paragraphs:paragraphs
  - webform:webform (>=8.x-5.x)

test_dependencies:
 - drupal:image

configure: hello_world.settings

php: 5.6

hidden: true
required: true

# 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. Core or contrib dependencies use the {project}:{module} format, where {project} is the Drupal.org project name and {module} is the machine name. You can also specify version constraints (e.g., webform:webform (>=8.x-5.x)). Dependencies on other provided modules/libraries should also be declared in your module’s composer.json file.
test_dependencies: Modules needed for automated testing (DrupalCI) but not required as runtime dependencies. Must be committed in Git before running tests. Alternatively, use Composer for test dependencies—see relevant documentation.
configure: If your module provides a configuration form, specify its route here. It will appear as a link in the "Extend" page (/admin/modules) when details are expanded.
php: 5.6: Defines the minimum required PHP version. Modules won't be enabled on unsupported PHP versions.
hidden: true: Hides the module from the "Extend" page module list. Useful for test-only or developer API modules. Can be revealed by setting $settings['extension_discovery_scan_tests'] = TRUE in settings.php.
required: true: Means the module must always be enabled and cannot be removed.
Restricted Properties: version and project are added by the Drupal packager. Do not include them manually in your info.yml.

Debugging .info.yml Files

Module Not Listed on admin/modules Page

Ensure the info file is named {machine_name}.info.yml and is in the root of the module folder.
Ensure the file is properly formatted: no spaces before colons, but one space after. Follow the provided examples.
Ensure the file includes this line:

type: module

Ensure the module name starts with a letter or underscore. PHP function names follow similar rules.

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, digits, or underscores. As a regex: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*.

Module Listed on admin/modules, but Checkbox Disabled

Ensure core compatibility is set to 8.x:

core: 8.x

Ensure all module dependencies are available. Expand module details to view missing requirements.

expand_requirements

Note that some modules have been removed from Drupal 8 core, while others have been added or replaced by new core modules.

Module Description is Empty

Remember, the description key is used for module description:

description: Example Module description.

Adding a composer.json File

In addition to declaring module dependencies in .info.yml, contributed modules on Drupal.org that want to test dependency changes using DrupalCI during development must include a composer.json file expressing those dependencies. (DrupalCI detects changes in composer.json only, not in .info/.info.yml files.)

Extra Block Types (EBT) - New Layout Builder experience❗

❗Extra Paragraph Types (EPT) - New Paragraphs experience