Skip to content
Shahid Malla

How to Install and Activate a WHMCS Module

Where each WHMCS module type belongs under /modules, the page that activates it, the admin role access addon modules need, the database rights activation uses, and how to read the Module Log when something fails.

· Published · 11 min read · 9 steps

To install a WHMCS module, upload its files to the folder under /modules that matches its type, then activate it on the settings page for that type: Addon Modules, Payment Gateways, Domain Registrars, or Servers. Addon modules also need admin roles ticked under Access Control. Activation changes the database, so the WHMCS database user needs its create and alter rights.

A WHMCS module is a PHP file, or a folder of PHP files, inside the /modules directory that WHMCS loads by name to add one capability: a control panel it can provision accounts on, a gateway it can charge through, a registrar it can register domains with, or an extra page in the Admin Area. WHMCS has no package manager and no upload button for modules, so the files reach the server by FTP, SFTP, SSH or a file manager. The Admin Area only lists a module once its files sit in the directory that type uses.

Five-step WHMCS module install workflow: check requirements, upload files to the right modules folder, activate, grant admin role access, then test with the Module Log
The order I install a bought module in. Source: shahidmalla.com.

Everything below is checked against the WHMCS 9.1 documentation, read on 21 November 2026. The WHMCS documentation home page listed 9.1 as General Availability that day, with 9.0 and 8.13 on Long-Term Support. If a vendor's instructions still say Setup > Addon Modules, that is an older menu; the current path is Configuration > System Settings > Addon Modules.

What do you need before you install a WHMCS module?

A supported WHMCS version, a PHP and ionCube Loader build the module can run on, a backup, and somewhere other than production to try it. The numbers come from the System Requirements page; they matter because a module runs inside the same PHP process as WHMCS.

CheckWhat the WHMCS 9.1 documentation statesWhy it matters here
WHMCS version9.1 General Availability, 9.0 and 8.13 Long-Term Support, earlier releases End of LifeVendors list supported versions
PHP versionPHP 8.2, 8.3 or 8.4PHP 7 module code fails here
ionCube Loader15.0.0 or higherCommercial modules ship encoded
Database privilegesALTER, CREATE, DROP and INDEX, needed for installs, updates, and activating or deactivating modulesActivation can create its own tables
File permissions644 for files, 755 for directories, owner and group matching the account user nameUploads inherit the wrong owner
The module's own requirementsCheck the Marketplace listing, which may add requirementscURL, SOAP or a minimum build

The privilege row is the one people miss: those four rights can be stripped from the WHMCS database user for daily operations, so grant them back before you click Activate. Back up first, and work on a staging copy if you have one, because deactivating an addon module can remove its data. On an older release, do the version work first: my WHMCS 9 upgrade guide covers that order.

Which folder does a WHMCS module go in?

One of four, decided by what the module does, not by who sold it. A module in the wrong folder never appears at all.

Module typeDirectoryWhere you activate itWhere it then appears
Addon module/modules/addonsConfiguration > System Settings > Addon ModulesThe Addons menu
Payment gateway/modules/gateways, callback file in /modules/gateways/callbackConfiguration > Apps & Integrations, then System Settings > Payment GatewaysOrder form and invoices
Domain registrar/modules/registrarsConfiguration > System Settings > Domain RegistrarsAuto Registration at Domain Pricing
Server or provisioning/modules/serversConfiguration > System Settings > Servers, Add New ServerThe Type menu on a server
Decision flow matching a WHMCS module to its directory: server modules, gateways, registrars and addons each land in one folder under /modules, anything else goes back to the vendor
How I place a module I have not seen before. Source: shahidmalla.com, from the WHMCS 9.1 module directories.

In words: if it creates accounts on a server, /modules/servers; if it takes payment on an invoice, /modules/gateways; if it registers or renews domains, /modules/registrars; if it adds an Admin Area or Client Area page, /modules/addons. If none fit, ask the vendor; some products ship two modules at once. My guide on WHMCS module types covers each type's functions.

How do you upload the WHMCS module files?

Unzip the package on your own machine first and look at the structure, because vendors ship two shapes. Some hold a bare module folder you drop into one of the four directories. Others hold a tree that already starts with modules/, which merges at the WHMCS root so nothing lands at /modules/addons/modules/addons/.

  • Keep the names the vendor shipped. WHMCS addresses a module by its directory name, so renaming the folder stops activation working.
  • Upload the callback file separately. The WHMCS payment gateway installation page puts a gateway's callback file in /modules/gateways/callback/, not in the gateway folder.
  • Fix ownership and permissions afterwards. Set 644 on PHP files, 755 on directories, owner and group matching the account user name. Files left owned by root are a common cause of a module WHMCS cannot read.
  • Do not patch a module that ships with WHMCS. Edits inside a shipped directory are replaced at the next update. The Refresh a Directory page covers the recovery: upload the clean directory from the matching file set, rename the old one with a date, then copy customizations back one by one.

How do you activate a WHMCS addon module?

Go to Configuration > System Settings > Addon Modules and work down the page. The Addon Modules documentation gives these steps, and the order is not optional.

  1. Upload the unzipped files to /modules/addons. You cannot configure an addon module until it is on the installation.
  2. Click Activate for that module, then Configure.
  3. Set the module's own settings if it has any, such as an API or license key.
  4. Select the administrator roles that should reach it under Access Control.
  5. Click Save Changes. The module now appears in the Addons menu.

Access Control is the step people skip: a module can be active, configured and still invisible because no role was ticked. To open one module to a third-party developer rather than the whole team, the Admins documentation gives the narrow version: enable the Addon Modules permission on that role, enable whatever else the module touches, then grant that admin access under Access Control. Its example also needs View Clients Summary, because the module adds a field to the client Summary tab.

How do you activate a gateway, registrar or provisioning module?

Each type has its own page, and only addon modules end with the Access Control step above.

  • Payment gateways. The Payment Gateways page activates a new gateway from Configuration > Apps & Integrations: find it, click Activate, then configure it at System Settings > Payment Gateways. Every gateway shares Show on Order Form, Display Name and Convert To For Processing. The developer documentation adds a warning: activation detects what kind of module was written, so if a new gateway behaves oddly, deactivate and reactivate it first.
  • Domain registrars. At Configuration > System Settings > Domain Registrars, click Activate, then enter your account details. The Domain Registrars page adds two steps people forget: set the default nameservers in the Domains tab of General Settings, and choose the registrar per TLD from the Auto Registration menu at Domain Pricing. Until that second step, the module is active but unused.
  • Server and provisioning modules. There is no Activate button. Go to Configuration > System Settings > Servers, click Add New Server and pick the module under Type, then fill in what the Servers page lists: hostname, IP address, username, and a password, API token or access hash. Default ports include cPanel on 2086 or 2087 with SSL and DirectAdmin on 2222. Plesk is the exception: a custom Plesk port such as 8443 goes in Access Hash, not Port.

A provisioning module only starts working once a product points at that server or server group. If you are writing one rather than buying one, my guide to WHMCS custom provisioning modules covers the function set.

How do you test a WHMCS module before clients use it?

Run one real action through it with logging on, then turn logging off. This is the checklist I work through.

  • Confirm the module is listed where its type belongs, not only that activation reported success.
  • Go to Configuration > System Logs, click Module Log, set Module Logging to On, reproduce one action, then refresh the log. Logs in WHMCS names two prerequisites: the View Module Debug Log permission on your role, and the DROP privilege granted temporarily to the database user.
  • Read entries for what they are. Module Command Errors come from the module and not from WHMCS, so they go to the vendor; Unknown Errors are errors WHMCS does not recognize.
  • For a gateway, check Billing > Gateway Log too. Returns record as Successful, Invalid or Error.
  • For a provisioning module, the documented debugging permissions are Configure Servers, View Clients Products/Services, View Module Debug Log and Perform Module Command Operations. Failed actions collect at Utilities > Module Queue.
  • Set Module Logging back to Off when you finish, and turn off Display Errors if you enabled it, because it shows verbose detail to clients too.

Why does a WHMCS module not show up after you activate it?

Almost always because the files are not where WHMCS looks, or the admin role was never granted access. The documented causes, in the order I check them:

What you seeDocumented causeWhat to do
An addon module is missing from the Addons menuThe module is not present on the system, or the necessary administrator roles were not selectedCheck the files in /modules/addons, then your role under Access Control
Apps & Integrations offers "Get it from the WHMCS Marketplace"That action only shows when the application is not present on the systemProof WHMCS cannot see your upload: wrong directory, name or ownership
A blank page or error on Payment Gateways after uploadingA syntax error in the new codeEnable Display Errors in the Other tab of General Settings, then disable it
Activation fails with a database errorThe database user lacks the rights activation usesGrant ALTER, CREATE, DROP and INDEX, then activate
A module worked, then stopped after a WHMCS updateFiles in a shipped directory were replacedFollow Refresh a Directory, restoring customizations one at a time

If the symptom is not in that list, my WHMCS troubleshooting guide starts from the logs.

What are the risks of installing a third-party WHMCS module?

A module runs with the same access as WHMCS itself, so weigh it like a database login.

  • You usually cannot read it. Commercial modules ship encoded with ionCube, so you are trusting the vendor with your billing database and gateway credentials.
  • Activation writes to your database. It uses CREATE and ALTER rights for a reason, and the documentation warns that disabling an addon module may delete relevant data.
  • Dead modules linger. A gateway with live subscriptions or a registrar with live domains cannot simply be deleted.

Before buying, check the vendor's listed requirements and that the module names a current WHMCS version. My comparison of the best WHMCS addons and modules covers how to check a vendor, and patching them later is WHMCS support and maintenance work.

How do you remove a WHMCS module safely?

Back up first, confirm nothing still uses the module, remove it inside WHMCS, then delete the files. All four module pages repeat the same advice: a full database and filesystem backup before deleting modules, and ask the developer about extra steps for a custom or third-party module. The middle steps differ by type.

Four-step WHMCS module removal pipeline: take a full backup, confirm nothing still uses the module, remove it inside WHMCS, then delete its folder from modules
The removal order I follow. Source: shahidmalla.com, from the WHMCS 9.1 addon, gateway, registrar and server module pages read 21 November 2026.
  • Addon module: click Deactivate, then delete the folder from /modules/addons.
  • Payment gateway: click Deactivate and pick an alternative when WHMCS prompts. That blocks new payments and reassigns services, invoices, transactions and pay methods to the gateway you choose. Then delete the files.
  • Domain registrar: deactivate it, confirm no domains still use it, then delete the files.
  • Server or provisioning module: make sure no products or services use it, delete the associated servers, then delete the files. Deleting a server first needs its hosting accounts reassigned, including canceled and terminated ones.

What else do people ask about installing WHMCS modules?

Can I install a WHMCS module without FTP access?

Yes, as long as you can put files on the server another way: SFTP, SSH, or the file manager in cPanel, Plesk or DirectAdmin. Apps & Integrations can send you to the WHMCS Marketplace to download a module, but you still place the files yourself.

Do I need a Full Administrator role to activate a WHMCS module?

Not necessarily. An addon module needs the Addon Modules permission on the role plus that role ticked under Access Control. I activate as a full administrator and then grant the narrower roles, because a half-granted role looks exactly like a failed install.

Can I install a WHMCS module on WHMCS Cloud?

Not the way you would on your own server. The Custom Modules page says its information applies only to self-hosted installations and that WHMCS Cloud does not currently support that customization method. Individual modules carry the same limit: the Configurable Package Addon is listed as self-hosted only. Ask WHMCS about a specific module before you buy.

Why did my module stop working after a WHMCS update?

Usually because the update replaced files it owns, or because the module has not been rebuilt for the current PHP and ionCube Loader versions. WHMCS 9.1 requires ionCube Loader 15.0.0 or higher and runs on PHP 8.2 to 8.4, so a module built for an older stack can stop loading the moment you upgrade.

If a module you bought will not run, or you want one built rather than bought, I take that on as WHMCS custom module development and as part of my wider WHMCS work, with a free scoping call of about 30 minutes and a written quote within one business day.

Last reviewed 21 November 2026. Disclosure: I am a freelance WHMCS developer and I sell custom WHMCS modules and integrations, so I am not neutral. I am CTO at ElySpace, a freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI.

Share this article

Shahid Malla

Written by

Shahid Malla

Freelance WHMCS developer and web designer with 13+ years of client work. CTO at ElySpace, freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI.

Got a project like this?

Tell me what you need and I will send a written quote within one business day.