Understanding the .info.yml File in Drupal Module Developmentfor Drupal 8 , 9 , 10 , and 11

Home » Module Development » Understanding the .info.yml File in Drupal Module Development
Last updated :  
8.x , 9.x , 10.x , 11.x

The .info.yml file is the heart of any Drupal module. It acts like a registration form, telling Drupal about your module's existence, its purpose, and how it integrates with the system. For beginners, think of it as the module’s ID card, containing key details like its name, type, and compatibility. In this tutorial, we’ll break down the hello_world.info.yml file from our "Hello World" module, explain each line, and guide you through creating it step-by-step. This is part of our Drupal module development series, designed for newcomers to Drupal 10 or 11 (as of 2025).

By the end, you’ll understand the structure of the .info.yml file, why each part matters, and how to avoid common mistakes. Let’s get started!

 

What is the .info.yml File?

The .info.yml file is a YAML-formatted file required for every Drupal module. It provides metadata that Drupal uses to recognize and manage the module. Without it, your module won’t appear in the Drupal admin interface (/admin/modules) or be installable. This file defines the module’s name, description, type, and compatibility, and can include optional settings like dependencies or versioning.

For our "Hello World" module, the file is named hello_world.info.yml and lives in the module’s root folder (/modules/custom/hello_world/). Let’s dissect the example:

 
name: 'Hello World'
type: module
description: 'This is a Hello world module'
package: Custom
core_version_requirement: ^10 || ^11
 

Step-by-Step Breakdown of the .info.yml File

Each line in the file serves a specific purpose. Here’s a beginner-friendly explanation of each key, why it’s needed, and how to use it correctly.

Step 1: Name (name)

Line: name: 'Hello World'

  • Purpose: The human-readable name of your module, displayed in the Drupal admin interface (/admin/modules). This is what users see when enabling or managing the module.
  • Explanation: Use a clear, descriptive name like "Hello World" to make it easy to identify. Avoid using the machine name (e.g., hello_world) here; the machine name is derived from the file name (hello_world.info.yml).
  • Best Practice: Keep it short but meaningful. For example, "User Login Enhancements" is better than "My Custom Module for Logins".
  • Common Mistake: Don’t skip this key—it’s required, or Drupal won’t recognize the module.

Example Image Idea: A screenshot of the Drupal admin interface (/admin/modules) showing "Hello World" listed under the "Custom" package. (Would you like me to generate this image for clarity?)

Step 2: Type (type)

Line: type: module

  • Purpose: Tells Drupal what kind of component this is. For modules, it’s always module. (Other options include theme for themes or profile for installation profiles.)
  • Explanation: This ensures Drupal knows to treat the component as a module and load it appropriately during the module discovery process.
  • Best Practice: Always set type: module for custom modules. It’s required.
  • Common Mistake: Typos (e.g., type: modules) will cause Drupal to ignore the module.

Step 3: Description (description)

Line: description: 'This is a Hello world module'

  • Purpose: A brief summary of what the module does, shown in the admin interface next to the module name. It helps users understand the module’s functionality.
  • Explanation: For our "Hello World" module, the description indicates it’s a simple module that displays a greeting. Keep it concise but informative.
  • Best Practice: Write a clear description, ideally under 255 characters, to avoid truncation. For example, "Displays a custom Hello World page at /hello."
  • Common Mistake: Vague descriptions (e.g., “Custom module”) make it hard for others to understand the module’s purpose. Also, don’t omit this key—it’s required.

Example Image Idea: A screenshot of the module list in Drupal’s admin interface, highlighting the description “This is a Hello world module” next to the module name. (Confirm if you’d like me to generate this.)

Step 4: Package (package)

Line: package: Custom

  • Purpose: Groups related modules together in the admin interface for better organization. For example, all Views-related modules might be grouped under “Views”.
  • Explanation: We use Custom to indicate this is a custom module, not part of a specific category like “Core” or “Commerce”. This groups it under a “Custom” section in /admin/modules.
  • Best Practice: Choose a logical package name if your module fits a category (e.g., “Search” or “Media”). For one-off modules, Custom is fine.
  • Common Mistake: This key is optional, but omitting it places the module in a generic “Other” category, which can make it harder to find.

Step 5: Core Version Requirement (core_version_requirement)

Line: core_version_requirement: ^10 || ^11

  • Purpose: Specifies which Drupal versions the module is compatible with. This ensures the module only runs on supported versions.
  • Explanation: The ^10 || ^11 syntax means the module works with Drupal 10.x or 11.x (but not 12 or earlier versions like 9). The ^ indicates compatibility with minor updates (e.g., 10.0, 10.1), and || allows multiple major versions.
  • Best Practice: Always include this for Drupal 8.7.7+ or later, as it replaces the older core: 10.x key. Test compatibility to ensure accuracy.
  • Common Mistake: Incorrect version syntax (e.g., core: 10) or omitting this key can prevent the module from being enabled or cause errors on incompatible Drupal versions.

Image Example Idea: A screenshot of a code editor (e.g., VS Code) showing the hello_world.info.yml file with syntax highlighting, emphasizing the YAML structure. (Would you like me to generate this image?)

 

Creating the .info.yml File: Step-by-Step Guide

Now, let’s walk through creating the hello_world.info.yml file for your "Hello World" module. This assumes you’ve set up a Drupal 10/11 site and have a code editor ready.

Step 1: Create the Module Folder

  • Navigate to your Drupal site’s /modules/custom/ directory (e.g., cd web/modules/custom/).
  • Create a folder named hello_world. Use lowercase and underscores for the machine name.
  • Why? Drupal uses the folder and file name (hello_world.info.yml) as the module’s machine name, which must match for the module to be recognized.

Step 2: Create the .info.yml File

  • In the hello_world/ folder, create a file named hello_world.info.yml.
  • Use a code editor like VS Code or PhpStorm for proper YAML formatting.
  • Why? The file name must match the machine name exactly (e.g., hello_world.info.yml, not helloworld.info.yml).

Step 3: Add the Required Keys

  • Open hello_world.info.yml and paste the following:
name: 'Hello World'
type: module
description: 'This is a Hello world module'
package: Custom
core_version_requirement: ^10 || ^11
 
  • Why? These keys provide the minimum required metadata for Drupal to recognize and display the module.

Step 4: Save and Validate

  • Save the file with proper YAML syntax (use 2 spaces for indentation, no tabs).
  • Check for errors using a YAML validator (e.g., online tools or editor plugins).
  • Why? YAML is sensitive to formatting errors (e.g., incorrect spacing), which can prevent the module from being detected.

Step 5: Test the Module

  • Go to your Drupal site’s admin interface (/admin/modules).
  • Look for “Hello World” under the “Custom” package.
  • If it doesn’t appear, clear the cache: drush cr or use /admin/config/development/performance.
  • Enable the module by checking the box and clicking “Install” as shown in the Introduction.
  • Why? Drupal caches module info, so changes may not appear until the cache is cleared.
installing drupal module

Common Pitfalls for Beginners

  • Wrong File Name: Ensure the file is named <machine_name>.info.yml (e.g., hello_world.info.yml).
  • YAML Syntax Errors: Use 2-space indentation and avoid tabs. Validate with tools like yamllint.com.
  • Missing Required Keys: name, type, and description are mandatory. Omitting them causes Drupal to ignore the module.
  • Incorrect Version Syntax: Use core_version_requirement correctly (e.g., ^10 || ^11) to avoid compatibility issues.
  • File Location: Place the module in /modules/custom/, not /modules/ or other folders, to keep it organized.

 

Next Steps

You’ve now mastered the .info.yml file! This is the foundation for any Drupal module. In the next tutorial, we’ll explore the .routing.yml file to create custom pages, like the /hello path for our "Hello World" module.