How to Install WHMCS Modules: A Step-by-Step Guide

WHMCS modules extend the core functionality of your billing system, allowing you to integrate with new payment gateways, registrars, and provisioning servers. Installing them correctly is critical for system stability.

Understanding Module Types

Before installing, identify the type of module you have:

• Addon Modules: General functionality extensions (e.g., reports, utilities). Found in modules/addons/.
• Payment Gateways: Payment processors (e.g., Stripe, PayPal). Found in modules/gateways/.
• Registrars: Domain registrars. Found in modules/registrars/.
• Servers: Hosting provisioning (cPanel, Plesk). Found in modules/servers/.

Method 1: Marketplace Installation

For modules available in the official WHMCS Marketplace:

1. Log in to your WHMCS Admin Area.
2. Navigate to Setup > Addon Modules (or search "Marketplace").
3. Browse or search for the module.
4. Click Install or Buy Now.

Method 2: Manual Installation (FTP)

For custom or third-party modules:

Step 1: Extract Files

Unzip the module package locally. You should see a folder structure like modules/addons/modulename.

Step 2: Upload Files

Connect to your server via FTP. Navigate to your WHMCS root directory (often public_html/whmcs/ or just public_html/).

Upload the folders to merge them with your existing directory structure.

/your-whmcs-root/
└── modules/
    └── addons/
        └── your_new_module/

Step 3: Activate in Admin

Once uploaded:

1. Go to System Settings > Addon Modules.
2. Find your new module in the list.
3. Click Activate.
4. Click Configure to set access permissions (check "Full Administrator").
5. Click Save Changes.

Troubleshooting Common Errors

"Module Not Found"

If the module doesn't appear in the list, verify the folder path. It must be exactly modules/addons/folder_name/hooks.php (or similar). Double-nested folders (e.g., modules/addons/folder/folder/) will fail.

"Access Denied"

Ensure you checked the specific admin role group in the Configure settings after activation.

PHP Version Mismatch

Some modules are encoded (IonCube) and require specific PHP versions. Check the module documentation against your server's PHP version (Utilities > System > PHP Info).