Magento 2 module.xml

The module.xml file declares the module's identity, version, and dependencies. It's the primary configuration file that tells Magento about the module.

Basic module.xml:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_Module" setup_version="1.0.0">
        <sequence>
            <module name="Magento_Catalog"/>
            <module name="Magento_Customer"/>
        </sequence>
    </module>
</config>

Module attributes:

• name - Unique module identifier (Vendor_Module format)
• setup_version - Current version for schema/data upgrades
• sequence - Dependencies that must load first

Location: app/code/{Vendor}/{Module}/etc/module.xml

Naming rules:

• Module name: Vendor_Module (Vendor and Module in PascalCase)
• Must match the name in registration.php
• Must be unique across the entire Magento installation

The <sequence> element defines hard dependencies - modules that must be loaded before your module.

Dependencies XML:

<module name="Vendor_Module" setup_version="1.0.0">
    <sequence>
        <!-- Hard dependencies -->
        <module name="Magento_Catalog"/>
        <module name="Magento_Customer"/>
        <module name="Magento_Inventory"/>
    </sequence>
</module>

What dependencies affect:

1. Load order - Dependent modules load first
2. Schema upgrades - Dependencies upgrade before your module
3. Class availability - Dependent classes are available
4. Configuration merging - Dependencies' XML loads first

Dependency rules:

• No circular dependencies allowed
• Dependencies must exist in the system
• Keep dependencies minimal and focused

Check dependencies:

# View module dependencies
php bin/magento module:status --dependencies

# Check for dependency issues
php bin/magento setup:di:compile 2>&1 | grep -i dependency

Soft dependencies (suggested):

<module name="Vendor_Module" setup_version="1.0.0">
    <sequence>
        <module name="Magento_Catalog"/>
    </sequence>
    <suggest>
        <module name="Magento_Inventory"/>
        <module name="Magento_Elasticsearch"/>
    </suggest>
</module>

<suggest> elements indicate optional dependencies that enhance functionality but aren't required.

The setup_version attribute tracks your module's schema and data version for upgrade management.

Version format:

• Semantic versioning: MAJOR.MINOR.PATCH
• Example: 1.0.0, 1.1.0, 2.0.0

When to increment:

• PATCH (1.0.0 → 1.0.1): Bug fixes, minor changes
• MINOR (1.0.0 → 1.1.0): New features, backward compatible
• MAJOR (1.0.0 → 2.0.0): Breaking changes

Upgrade scripts:

app/code/Vendor/Module/Setup/
├── InstallSchema.php      # First install
├── UpgradeSchema.php      # Schema changes
├── InstallData.php        # Initial data
└── UpgradeData.php        # Data changes

InstallSchema.php:

<?php
namespace Vendor\Module\Setup;

use Magento\Framework\Setup\ModuleContextInterface;
use Magento\Framework\Setup\SchemaSetupInterface;

class InstallSchema implements \Magento\Framework\Setup\InstallSchemaInterface
{
    public function install(SchemaSetupInterface $setup, ModuleContextInterface $context)
    {
        $setup->startSetup();
        
        $table = $setup->getConnection()->newTable(
            $setup->getTable('vendor_module_items')
        )
        ->addColumn(
            'entity_id',
            \Magento\Framework\Db\Ddl\Table::TYPE_INTEGER,
            null,
            ['identity' => true, 'unsigned' => true, 'nullable' => false, 'primary' => true],
            'Entity ID'
        )
        ->addColumn(
            'name',
            \Magento\Framework\Db\Ddl\Table::TYPE_TEXT,
            255,
            ['nullable' => false],
            'Name'
        );
        
        $setup->getConnection()->createTable($table);
        $setup->endSetup();
    }
}

UpgradeSchema.php:

public function upgrade(SchemaSetupInterface $setup, ModuleContextInterface $context)
{
    $setup->startSetup();
    
    if (version_compare($context->getVersion(), '1.1.0', '<')) {
        // Add new column
        $setup->getConnection()->addColumn(
            $setup->getTable('vendor_module_items'),
            'status',
            [
                'type' => \Magento\Framework\Db\Ddl\Table::TYPE_SMALLINT,
                'nullable' => false,
                'default' => 1,
                'comment' => 'Status'
            ]
        );
    }
    
    $setup->endSetup();
}

Run upgrades:

php bin/magento setup:upgrade

Magento compares setup_version with the database record and runs appropriate upgrade scripts.

Follow these best practices for module declaration and version management.

Complete module.xml example:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_Module" setup_version="1.2.0">
        <sequence>
            <module name="Magento_Catalog"/>
            <module name="Magento_Store"/>
        </sequence>
        <suggest>
            <module name="Magento_Inventory"/>
        </suggest>
    </module>
</config>

Best practices:

1. Minimal dependencies - Only list modules you actually use
2. Version every schema change - Increment setup_version for any DB change
3. Separate install and upgrade scripts - Keep InstallSchema clean, put changes in UpgradeSchema
4. Use version_compare - Always check current version in upgrade scripts
5. Test upgrades - Test both fresh install and upgrade paths

Common issues:

# Module not appearing in list
php bin/magento module:status Vendor_Module
# Check registration.php and module.xml exist

# Version conflict
php bin/magento setup:upgrade
# Check setup_version matches DB record

# Dependency not found
php bin/magento module:status --dependencies
# Ensure dependency module is installed

View module information:

# Show module details
php bin/magento module:status Vendor_Module --version

# Check DB version
mysql -u root -p magento -e "SELECT * FROM setup_module WHERE module='Vendor_Module';"

Module version lifecycle:

1. Create module with setup_version="1.0.0"
2. Run setup:upgrade → creates DB record
3. Make changes → increment to 1.1.0
4. Run setup:upgrade → runs UpgradeSchema/UpgradeData
5. Repeat for each version bump