How to Install WHMCS Modules Safely

Installing a WHMCS module sounds simple — upload files, click activate. The 10% that goes wrong does so in characteristic ways, and undoing a bad install is harder than installing right the first time.

This is the install procedure I follow for every WHMCS module, free or paid, marketplace or custom.

Step 1 — Verify the module before uploading anything

Before unzipping:

• Confirm compatibility with your WHMCS version. Marketplace listings show "Compatible with WHMCS X.X". If unclear, email the vendor.
• Confirm PHP version support. WHMCS 8.x defaults to PHP 8.1+; some older modules ship for PHP 7.4 only.
• Read the module's docs / README. If a module ships without docs, treat that as a warning sign.
• Skim the source code if you can. Look for outdated WHMCS API calls, hardcoded paths, suspicious file operations.

Step 2 — Install on staging first (above any production scale)

If your install has any real customers, install the new module on staging first. Reasons:

• A bad PHP file can crash WHMCS entirely (white screen for everyone).
• The module may run database migrations on activation that you can't reverse.
• You can't load-test on production safely.

Spin up a staging copy of WHMCS — same DB schema, recent data dump, dev license — and install there.

Step 3 — Upload files to the right directory

The directory depends on module type:

Inside the type folder, each module gets its own subfolder named the same as the main PHP file:

/modules/addons/mymodule/
  mymodule.php       # main file (must match folder name)
  hooks.php          # optional, module-specific hooks
  templates/         # optional, module's templates
  install.sql        # optional, schema migrations
  README.md          # documentation

Upload via SFTP or your file manager. Avoid copy/paste through a terminal: invisible character changes (like smart quotes) break PHP.

Step 4 — Set correct file permissions

chown -R www-data:www-data /path/to/whmcs/modules/addons/mymodule/
chmod -R 755 /path/to/whmcs/modules/addons/mymodule/
chmod 644 /path/to/whmcs/modules/addons/mymodule/*.php

Adjust user/group to match your web server (nginx, apache, custom). PHP files should be readable but not writable by the web server.

Step 5 — Activate in WHMCS admin

Different module types activate differently:

• Addon: Setup → Addon Modules → find your module → Activate.
• Payment gateway: Setup → Payments → Payment Gateways → All Payment Gateways → find yours → Activate.
• Domain registrar: Setup → Domain Registrars → find yours → Activate.
• Provisioning: no activation step; you reference the module by name when configuring a product.
• Reports: auto-discovered; appears under Reports → custom report.
• Hooks: no activation; loaded automatically on every page.

Step 6 — Configure

Open the module's settings page (admin nav location varies — usually under Setup → Addon Modules → Configure for addons, or in the gateway/registrar config screens for those types).

Fill in:

• API keys / credentials.
• Behavior toggles per the module's docs.
• Permissions — which admin roles can use this module.

Save. Most modules have a "Test Connection" or similar — use it.

Step 7 — Verify end-to-end

1. Check Utilities → Logs → Activity Log — module's activation should be logged.
2. Check Utilities → Logs → Module Log for any errors.
3. Test the feature the module provides (place an order, run a report, etc.).
4. Test from a non-admin context (impersonate a client) to confirm permissions are right.
5. Confirm WHMCS page load times haven't increased noticeably.

Step 8 — Knowing how to roll back

If something breaks:

1. Deactivate from the admin UI, if you can still reach the admin.
2. If the admin is broken (white screen): SSH in and delete the module folder. WHMCS will skip it on next request.
3. If the module ran DB migrations: you may need to manually reverse them. Check the module's docs or `install.sql` for hints.
4. If you're truly stuck: restore from your pre-install backup. (You did take one, right?)

Step 9 — Track what you installed

Maintain a record per WHMCS install:

This pays off when you do WHMCS upgrades — you'll know which modules to verify compatibility for.

Common pitfalls

"Module not detected after upload." Folder name doesn't match the PHP file name, or you uploaded to the wrong type's directory. /modules/addons/mymodule/mymodule.php is correct.

"Module shows in list but won't activate (white screen on click)." A PHP error in the module file. Enable Display Errors temporarily; reload; read the error.

"Module activated, then deactivated itself." The module has a license check that's failing (talks home, fails, refuses to run). Confirm the license is valid, the server has outbound HTTPS, the license key is entered correctly.

"Module's database table didn't get created." Activation hook didn't run, or threw an error silently. Check if the module has an install.sql — run it manually. Or call the activation function directly via tinker.

"Permissions error on upload." Files owned by wrong user. chown -R to match your web server.

My take — module hygiene matters

1. Don't install on a whim. Each module is potential incident surface area.
2. Uninstall what you stop using. Dormant modules collect cruft and add to upgrade complexity.
3. Build a hook instead when the use case is simple. A 50-line hook is easier to maintain than a 2,000-line marketplace module that does the same thing.
4. Audit installed modules quarterly. See what's actually in use vs. just installed.

Going further

• WHMCS addon module documentation
• My module development guide — for when you need to build your own.
• My recommended module shortlist

I install, audit, and right-size WHMCS module stacks for hosting businesses. Tell me what you're trying to add and I'll send a quote in 24 hours.