How do you install a SuiteCRM theme?
To install a SuiteCRM theme, open Admin > Module Loader as an administrator, upload the theme ZIP, click Install, accept the licence and click Commit, then run Admin > Repair > Quick Repair and Rebuild. SuiteCRM 8 also needs the theme's extension folder copied into extensions/ and php bin/console cache:clear run from the SuiteCRM root.
Steps at a glance
- Check your exact SuiteCRM version. Read $suitecrm_version in suitecrm_version.php (SuiteCRM 7) or public/legacy/suitecrm_version.php (SuiteCRM 8) and use a package built for that minor version.
- Open Module Loader. Log in as an administrator and go to Admin > Module Loader.
- Upload the package. Click Upload and choose the theme ZIP file.
- Install and commit. Click Install, accept the licence agreement, then click Commit and wait for Module Installed Successfully.
- Quick Repair and Rebuild. Go to Admin > Repair and run Quick Repair and Rebuild so the new stylesheet is served immediately.
- SuiteCRM 8 only: install the extension. Copy the extension folder into <suitecrm>/extensions/, make it readable by the web server, then run php bin/console cache:clear from the SuiteCRM root.
- Select the theme and hard-refresh. Choose the sub-theme under Profile > Edit > Layout Options > Style if it is not already the default, then reload with Ctrl-F5 or Cmd-Shift-R.
Before you start: match the version
Theme packages are usually built for a specific SuiteCRM release, because the stock theme files they extend change between versions. Check yours before you upload anything:
| SuiteCRM | Version file | Line to read |
|---|---|---|
| 7.x | suitecrm_version.php in the SuiteCRM root | $suitecrm_version |
| 8.x | public/legacy/suitecrm_version.php | $suitecrm_version |
A well-built package refuses the wrong version before it copies a single file. A Brandtint package, for example, stops with a message like "This package was built for SuiteCRM 7.13 and cannot be installed on SuiteCRM 7.14.6. Download a package built for this version instead." If you see that, download the package for your version rather than editing the manifest.
Installing on SuiteCRM 7
- Log in as an administrator and go to Admin > Module Loader.
- Click Upload and select the theme ZIP.
- Click Install next to the uploaded package, accept the licence agreement, then click Commit. Wait for "Module Installed Successfully".
- Go to Admin > Repair and run Quick Repair and Rebuild. This clears the compiled theme cache so the new stylesheet is served straight away.
- If the package did not set itself as the default, each user can choose it under Profile > Edit > Layout Options > Style. SuiteCRM has no admin screen for the default sub-theme (Admin > Themes picks the theme, SuiteP, not its sub-theme), so an administrator sets the site default with one line in
config_override.php:$sugar_config['theme_settings']['SuiteP']['sub_themes'] = 'YourName';
Installing on SuiteCRM 8 (two parts)
SuiteCRM 8 draws its screens with two themes: the classic views (Admin, Studio and most record views) and the Angular shell (top bar, side panel and converted modules). Module Loader can only write inside public/legacy/, so it can install the first but never the second. A complete SuiteCRM 8 theme therefore comes in two parts.
Part 1, classic views, through Module Loader:
- Go to Admin > Module Loader, upload the package ZIP, click Install, then Commit.
- Run Admin > Repair > Quick Repair and Rebuild.
Part 2, Angular screens, as an extension (needs server access):
- Copy the theme's extension folder into
<suitecrm>/extensions/. - Make it readable by the web server, for example
chown -R www-data:www-data <suitecrm>/extensions/<folder>. - From the SuiteCRM root, run
php bin/console cache:clear. This is required: it registers the extension and publishes its stylesheet. - Reload SuiteCRM and hard-refresh (Ctrl-F5, or Cmd-Shift-R on a Mac).
Either part works on its own, but installing only one leaves the other half of the interface in stock colours.
Removing a theme: Uninstall, not Disable
Module Loader's Disable does not switch a theme off. SuiteCRM has no disable hook and does not delete the files a package copied, so users keep seeing the theme. Uninstall is the off switch: a well-built theme package restores the previous site default and each user's previous sub-theme on uninstall, and removes its own files. Run Quick Repair and Rebuild afterwards.
On SuiteCRM 8, also delete the extension folder from extensions/ and run php bin/console cache:clear again.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Install refused with a version message | Package built for a different minor version | Download the package for your exact version |
| Theme installed but nothing changed | Old stylesheet still cached | Quick Repair and Rebuild, then hard-refresh the browser |
| SuiteCRM 8: classic views branded, top bar stock | Extension half not installed, or cache not cleared | Copy the extension into extensions/ and run php bin/console cache:clear |
| Upload rejected by the package scanner | Module Loader's optional packageScan is on; its blacklist includes basic file functions like mkdir and copy that any theme installer needs | Turn the scan off for the install, or ask your host to |
| Theme still visible after Disable | Disable never removes copied files | Use Uninstall |
Questions
Do I need a developer to install a SuiteCRM theme?
Not on SuiteCRM 7: Module Loader is a browser upload and two clicks. On SuiteCRM 8 the classic-view half installs the same way, but the Angular half needs a folder copied to the server and one command run (php bin/console cache:clear), which whoever hosts your SuiteCRM can do in a few minutes.
Why does Module Loader say the package is not compatible with my version?
Theme packages are often locked to the SuiteCRM minor version they were built for, because the stock theme files change between releases. Check $suitecrm_version in suitecrm_version.php (public/legacy/ on SuiteCRM 8) and use a package built for that version.
What is the difference between Disable and Uninstall in Module Loader?
Disable keeps the package's files in place, so a theme stays visible. Uninstall runs the package's removal steps and deletes its files; for a well-built theme it also restores the theme each user had before.
About the author
Muhammad Ilyas builds Brandtint at Techholds, including the SuiteCRM 7 and SuiteCRM 8 theme packages these guides are written from. Muhammad Ilyas on LinkedIn