June 28, 2022
How to create a custom module in Magento 2.

eMarketer predicts that retail ecommerce sales will grow from $4.9 trillion in 2021 to $7.4 trillion by 2025. If you want to leverage this growth, learning how to create a custom module in Magento 2 can help you boost sales by adding custom functionality to your online store.

A Magento module is a logical group (directory) of blocks, controllers, helpers, and models related to a specific business function such as shipping or payment. Its primary purpose is to add or extend features without risking the integrity of the Magento codebase.

Here, we’ll teach you the basics of how to create a custom module in Magento 2.

Ready to learn? Let’s get started.

How To Create a Custom Module in Magento 2

1. Create the custom module directory.

2. Create the etc/module.xml declaration file.

3. Create a registration.php file for the module.

4. Register and install the module using the php bin/magento setup:upgrade script.

5. Verify that the module is enabled.

Get fully managed Magento hosting

Accelerate your store's potential, without the tedious maintenance

Create the Custom Module Directory

Before you create a folder for your custom module, you need to decide where you will place it. You can place a custom module in Magento 2 in the app/code directory or the vendor/ folder.

If you’re creating a custom module for a single project, you can place it in the app/ directory. However, if you’re building a custom extension to distribute and reuse on other Magento stores, you should use Composer to create it and place it in the vendor/ folder.

Once you’ve finalized the location, you need to name the module based on the PSR-0 standard.

A Magento 2 custom module name must contain the vendor name and the module name. Naming it this way also makes it easy to group modules by vendors in the project directory and allows a single vendor directory to contain multiple module subdirectories.

We’ll create a module directory in the app/code folder for this tutorial and name the vendor directory “Nexcess” and the module subdirectory “CustomModule.”

To create the module directory structure, log in to the backend Magento server as the filesystem owner and execute the following command from the Magento project root directory:

$ mkdir -p app/code/Nexcess/CustomModule

This command executes silently in the background. You can verify the folder structure has been created by using the following command:

$ ls -R app/code

Check Magento 2 custom module directory structure.

If this is your first time adding a Magento 2 extension, the folder app/code may not exist in your Magento project. Using the mkdir command with the -p flag creates parent directories (where they don’t exist) and the target directory in a single command.

Create the etc/module.xml Declaration File

Once you’ve created the new module directory, you need to create the etc/module.xml file to list the module name, version, and dependencies.

The module name is determined by the folders created in the previous step. Since we named the folders Nexcess/CustomModule, our module will be called ‘Nexcess_CustomModule.’

The module version indicates the current version of the database schema and data. If you make changes to the table schema in your module, updating your module version will ensure it updates across all instances of your code in the Magento application.

We’ll list the initial version for our current module as 0.0.1.

The module dependencies list references any other modules your custom module depends on. We’ll make our simple custom module dependent on Magento’s core catalog module for this guide.

First, create the etc/ folder inside your module directory using the following command:

$ mkdir app/code/Nexcess/CustomModule/etc

Then, create the module.xml file using the nano text editor as follows:

$ nano app/code/Nexcess/CustomModule/etc/module.xml

Finally, paste the following code into it:

<?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="Nexcess_CustomModule" setup_version="0.0.1">


<module name="Magento_Catalog"/>




Magento 2 custom module declaration file.

You can add more module dependencies by adding the <module name=“...”/> node inside the sequence node. Make sure to replace the ellipsis (...) with the default values of your preferred Magento core modules.

Create a registration.php File for the Module

The next step in learning how to create a custom module in Magento 2 is creating the registration.php file in the module folder. This file helps Magento locate the module in its filesystem.

All modules in Magento 2 must contain a registration.php file. Without it, you cannot install a Magento 2 theme or extension on your store.

Use the following command to create the registration.php file using the nano text editor in the module’s root directory path:

$ nano app/code/Nexcess/CustomModule/registration.php

Then, paste the following content inside it:


use Magento\Framework\Component\ComponentRegistrar;






Magento 2 custom module registration file.

Register and Install the Module Using the php bin/magento setup:upgrade Script

Now that you’ve created a simple module, it’s time to activate it. This is the final step in learning how to create a custom module in Magento 2.

Run the following command from the Magento project root to install your basic module:

$ php bin/magento setup:upgrade

This command registers the custom module in Magento and upgrades the Magento database schema and data.

Verify That the Module Is Enabled

Generally, when you install a Magento 2 extension, you can verify that it is enabled in the Magento admin. However, because our module is empty, we’ll need to check the Magento configuration file containing the list of modules currently active via the command line.

Run the following command to verify your custom module is active:

$ grep Nexcess_CustomModule app/etc/config.php

You should see the following output:

Check Magento 2 configuration file.

Alternatively, use this command to check the module status:

$ php bin/magento module:status Nexcess_CustomModule

Check Magento 2 custom module status.


You’ve successfully created and installed a custom module in Magento 2. After this, you can take things a step further by adding custom routes, layouts, and templates to alter core modules and enhance front-end Magento functionality.

Final Thoughts: How To Create a Custom Module in Magento 2

Learning how to create a custom module in Magento 2 is only the first step toward customizing the design and functionality of your online store.

The possibilities of what you can do with a custom Magento 2 module are endless. However, you will need PHP, JS, HTML, and CSS skills to push the boundaries of Magento 2 module development.

Hosting your Magento store with Nexcess doesn’t need any special skills. You can build and run a Magento store in a few simple clicks. You get access to performance-optimized Magento servers, so you can focus on doing what you do best — growing your online business.

Browse our plans to learn more.

Maddy Osman
Maddy Osman

Maddy Osman is a WordPress expert, WordCamp US speaker, bestselling author, and the Founder and SEO Content Strategist at The Blogsmith. She has a B.A. in Marketing from the University of Iowa and is a WordCamp Denver organizer while also operating The Blogsmith, an SEO content agency for B2B tech companies that works with clients like HubSpot, Automattic, and Sprout Social. Learn more about The Blogsmith's process and get in touch to talk content strategy: www.TheBlogsmith.com

We use cookies to understand how you interact with our site, to personalize and streamline your experience, and to tailor advertising. By continuing to use our site, you accept our use of cookies and accept our Privacy Policy.