How-to Guides • January 16, 2026 • Admin

How to Install WHMCS Module: Complete Installation Guide 2026

How to Install WHMCS Module: Complete Installation Guide 2026

How to Install WHMCS Module: Complete Installation Guide 2026

Installing WHMCS modules is a straightforward process, but following the correct steps ensures smooth operation. This 2026 guide covers everything you need to know about installing WHMCS modules, including manual installation, activation, and troubleshooting.

Prerequisites

  • WHMCS installation (version 7.x or 8.x recommended)
  • Admin access to your WHMCS installation
  • FTP access or cPanel File Manager
  • Module files (usually in ZIP format)

Method 1: Automatic Installation (Recommended)

Step 1: Access Module Upload

  1. Log in to your WHMCS admin area
  2. Navigate to Setup > Addon Modules (for addon modules) or Setup > Products/Services > Servers (for server modules)
  3. Click "Upload New Module" or "Import Module"

Step 2: Upload Module File

  1. Click "Choose File" and select your module ZIP file
  2. Click "Upload"
  3. Wait for the upload to complete

Step 3: Activate Module

  1. After upload, the module will appear in your modules list
  2. Click "Activate" next to the module name
  3. Configure module settings if prompted

Method 2: Manual Installation

Step 1: Extract Module Files

Extract the module ZIP file to a temporary location on your computer.

Step 2: Upload Files via FTP

  1. Connect to your server via FTP (FileZilla, WinSCP, etc.)
  2. Navigate to your WHMCS root directory
  3. Upload module files to the appropriate directory:
    • Addon Modules: /modules/addons/
    • Server Modules: /modules/servers/
    • Gateway Modules: /modules/gateways/
    • Registrar Modules: /modules/registrars/

Step 3: Set File Permissions

Set appropriate file permissions:

  • Directories: 755
  • Files: 644
  • Configuration files: 600 (if sensitive)

Step 4: Activate in WHMCS Admin

  1. Log in to WHMCS admin area
  2. Navigate to the appropriate module section
  3. Find your module and click "Activate"

Installing Specific Module Types

Payment Gateway Modules

  1. Upload to /modules/gateways/
  2. Go to Setup > Payments > Payment Gateways
  3. Activate and configure the gateway
  4. Enter API credentials and test settings

Addon Modules

  1. Upload to /modules/addons/
  2. Go to Setup > Addon Modules
  3. Activate the module
  4. Configure module settings
  5. Assign admin permissions if needed

Server Modules

  1. Upload to /modules/servers/
  2. Go to Setup > Products/Services > Servers
  3. Add new server or edit existing
  4. Select the module from dropdown
  5. Configure server settings

Post-Installation Configuration

1. Configure Module Settings

Most modules require configuration after installation:

  • API credentials
  • Connection settings
  • Default values
  • Feature toggles

2. Set Permissions

For addon modules, configure admin permissions:

  1. Go to Setup > Staff Management > Administrators
  2. Edit administrator
  3. Enable module access under "Addon Modules"

3. Test Module Functionality

  • Create a test order (if applicable)
  • Verify module operations
  • Check error logs
  • Test in staging environment first

Common Installation Issues and Solutions

Issue 1: Module Not Appearing

Solution:

  • Check file permissions
  • Verify files are in correct directory
  • Clear WHMCS template cache
  • Check PHP error logs

Issue 2: Permission Denied Errors

Solution:

  • Set correct file permissions (755 for directories, 644 for files)
  • Check ownership (should match web server user)
  • Verify PHP can write to necessary directories

Issue 3: Module Activation Fails

Solution:

  • Check WHMCS version compatibility
  • Verify PHP version requirements
  • Check module log files
  • Review WHMCS system logs

Issue 4: Database Errors

Solution:

  • Ensure database user has CREATE/ALTER permissions
  • Check database connection settings
  • Run module installation SQL manually if needed

Best Practices for Module Installation

1. Always Backup First

  • Backup WHMCS files
  • Backup database
  • Document current configuration

2. Test in Staging Environment

Never install modules directly on production. Always test first in a staging environment.

3. Check Compatibility

  • Verify WHMCS version compatibility
  • Check PHP version requirements
  • Review module documentation

4. Keep Modules Updated

Regularly update modules to get security patches and new features.

Uninstalling Modules

Step 1: Deactivate Module

  1. Go to module settings
  2. Click "Deactivate"
  3. Confirm deactivation

Step 2: Remove Module Files

  1. Delete module directory from server
  2. Remove database tables (if module created any)
  3. Clean up any custom files

Step 3: Clear Cache

Clear WHMCS template cache and browser cache.

WHMCS 8.x Installation Notes

WHMCS 8.x includes improved module management:

  • Better error messages
  • Enhanced security checks
  • Improved compatibility validation
  • Streamlined activation process

Conclusion

Installing WHMCS modules is a simple process when you follow the correct steps. Always backup your installation, test in staging, and follow module-specific documentation for best results.

Need help with module installation? Check out our premium WHMCS modules which include detailed installation guides and support.

Related Articles

Related Articles