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.
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.
| Check | What the WHMCS 9.1 documentation states | Why it matters here |
|---|---|---|
| WHMCS version | 9.1 General Availability, 9.0 and 8.13 Long-Term Support, earlier releases End of Life | Vendors list supported versions |
| PHP version | PHP 8.2, 8.3 or 8.4 | PHP 7 module code fails here |
| ionCube Loader | 15.0.0 or higher | Commercial modules ship encoded |
| Database privileges | ALTER, CREATE, DROP and INDEX, needed for installs, updates, and activating or deactivating modules | Activation can create its own tables |
| File permissions | 644 for files, 755 for directories, owner and group matching the account user name | Uploads inherit the wrong owner |
| The module's own requirements | Check the Marketplace listing, which may add requirements | cURL, 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 type | Directory | Where you activate it | Where it then appears |
|---|---|---|---|
| Addon module | /modules/addons | Configuration > System Settings > Addon Modules | The Addons menu |
| Payment gateway | /modules/gateways, callback file in /modules/gateways/callback | Configuration > Apps & Integrations, then System Settings > Payment Gateways | Order form and invoices |
| Domain registrar | /modules/registrars | Configuration > System Settings > Domain Registrars | Auto Registration at Domain Pricing |
| Server or provisioning | /modules/servers | Configuration > System Settings > Servers, Add New Server | The Type menu on a server |
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.
- Upload the unzipped files to
/modules/addons. You cannot configure an addon module until it is on the installation. - Click Activate for that module, then Configure.
- Set the module's own settings if it has any, such as an API or license key.
- Select the administrator roles that should reach it under Access Control.
- 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 see | Documented cause | What to do |
|---|---|---|
| An addon module is missing from the Addons menu | The module is not present on the system, or the necessary administrator roles were not selected | Check 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 system | Proof WHMCS cannot see your upload: wrong directory, name or ownership |
| A blank page or error on Payment Gateways after uploading | A syntax error in the new code | Enable Display Errors in the Other tab of General Settings, then disable it |
| Activation fails with a database error | The database user lacks the rights activation uses | Grant ALTER, CREATE, DROP and INDEX, then activate |
| A module worked, then stopped after a WHMCS update | Files in a shipped directory were replaced | Follow 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.
- 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.