Development Guides Home >> Quickstart Development Guide

Tutorial - Create a Custom cPanel Style


This tutorial creates a custom cPanel style and applies it to the cPanel or Webmail interfaces.

For the purposes of cPanel, L.L.C.'s products and documentation, we use the following terms:

  • Branding — Branding modifies the cPanel interface in order to match your company's logo and brand. 

    • Branding changes include updates to image assets or text labels.
    • For more information, read our Branding documentation.
  • Includes — UI includes add custom content to the header or footer of the cPanel interface (but not the WHM interface). 

    • You can create UI includes for specific cPanel interfaces, or global UI includes that display on all of cPanel's interfaces. 
    • For more information, read our UI Includes documentation.
  • Plugin — A plugin modifies an interface's features or functionality, and it may also include changes to the interface's appearance.

    • You can write plugins for the cPanel or WHM interfaces.
    • You can use the cPanel Style Guide to ensure that your interfaces match the appearance of standard cPanel interfaces.
    • For more information, read our Guide to cPanel Plugins documentation.
  • Style — A style uses CSS, images, and other assets to modify the appearance of the entire cPanel interface without changes to its functionality or features. 

    • You can create and apply styles to an entire server or a specific reseller's accounts, or you can create them for distribution. 
    • For more information, read our cPanel Style Development documentation.
  • Theme — A theme applies an overlay on the skeletal framework for all of the interfaces.

    • cPanel & WHM currently ships with one default cPanel theme and one default WHM theme.
    • The Webmail and login interfaces also use themes.

We strongly recommend that you keep your custom styles up to date to avoid compatibility issues when you upgrade cPanel & WHM. To do this, perform the following actions:

  • Monitor our Change Logs and our Release Notes documentation for updated features and bug fixes.
  • Make certain that your server runs on the LTS, STABLE, RELEASE, or CURRENT release tiers, so that it receives any functionality updates.
  • You can also use a server that runs on the EDGE release tier to test for compatibility and functionality in a controlled environment.

You can download an example skeleton style to help you create a new style.

Create a custom cPanel style

Create a new directory for the new style.

Create the directory that will contain your style's styles.css file and its images and other assets.

To create a directory from the command line, run the following command, where mystyle represents your style's name:

mkdir mystyle

This tutorial moves the directory to the correct location in step 5. However, if you wish, you can create the directory in the appropriate location as part of step 1. 

Create the styles.css file.

Create the styles.css file within the directory that you just created. Use your preferred text editor to add the desired CSS code to the file.


This tutorial uses the styles.css file. However, in cPanel & WHM version 60 and later, you can also choose to use a minified styles.min.css file. We strongly recommend that you include both the styles.css and styles.min.css files.

Add custom icons.

You can replace the cPanel interface's default icons with custom icons for your style.

To replace the default cPanel icons with your own icons, perform the following steps:

  1. In your style's directory, create the icons subdirectory.
  2. Save your icons with the same name and file extension as the feature icons that you wish to replace. 

    • For example, to replace the File Manager icon, save a .png version of the icon as the file_manager.png file (cPanel & WHM version 58 and earlier) or an .svg version of the icon as the file_manager.svg file (cPanel & WHM version 60 and later).
    • For a full list of feature icon names, read our Guide to cPanel Interface Customization - Appkeys documentation.

For additional information about icon requirements, read our Guide to cPanel Interface Customization - Custom Icons and Logos documentation. 

Add a preview image.

To add a preview image to your custom style, save the image as the preview.png file within the style's directory.

  • cPanel's Change Style interface (cPanel >> Home >> Preferences >> Change Style) and WHM's Customization interface (WHM >> Home >> cPanel >> Customization) will display this image with the options for the style.
  • We recommend that you use a 500 by 500 pixel image as the preview image.

Move the style directory to the appropriate location on the server.


In cPanel & WHM version 60 and later, you can skip steps 5 through 7 of this tutorial. Instead, compress the style directory as a .tar.gz file, and then use WHM's Customization interface (WHM >> Home >> cPanel >> Customization) to upload and apply the style.

Use the mv command to move your style's directory to the appropriate location on the server:

  • For all of the accounts on the server — /var/cpanel/customizations/styled/mystyle/
  • For all of the cPanel accounts that a reseller owns — /home/reseller/var/cpanel/reseller/styled/mystyle/
  • For a specific cPanel account — /home/username/var/cpanel/styled/mystyle/
  • mystyle represents the name of the style's directory.
  • reseller represents the reseller's username.
  • username represents the cPanel account's username.
  • If the server uses a customized home directory path, make certain that you use the appropriate path for that home directory.
  • If these directories do not currently exist on the server, use the mkdir command to create them.

Apply the style.

Use the appropriate method to apply the style to one or more cPanel accounts on the server:

To apply a style as the server's default style, perform the following steps:

  1. Log in to the server via SSH as the root user. 
  2. Create the /var/cpanel/customizations/styled directory, if it does not already exist.
  3. Run the following command, where path_to_style represents the absolute path to the style that you wish to apply:
ln -s path_to_style /var/cpanel/customizations/styled/default_style

For example, to apply the /var/cpanel/customizations/styled/mystyle style, run the following command:

ln -s /var/cpanel/customizations/styled/mystyle /var/cpanel/customizations/styled/default_style

To apply a style to all of a reseller's accounts as the default style, perform the following steps:

  1. Log in to cPanel as the reseller. 
  2. Navigate to cPanel's Change Style interface (cPanel >> Home >> Preferences >> Change Style).
  3. Click Set as Default for the desired style.

To apply a style to a specific account through the cPanel interface, perform the following steps:

  1. Log in to cPanel as the desired user. 
  2. Navigate to cPanel's [Change Style](( interface (cPanel >> Home >> Preferences >> Change Style).
  3. Click Apply for the desired style.

To apply a style to a specific account through the command line, perform the following steps:

  1. Log in to the server via SSH as the desired user. 
  2. Run the following command, where username represents the cPanel account's username, and path_to_style represents the absolute path to the style that you wish to apply:

    ln -s path_to_style /home/username/var/cpanel/styled/current_style

    For example, to apply the /var/cpanel/customizations/styled/mystyle style for the username user, run the following command:

        ln -s /var/cpanel/customizations/styled/mystyle /home/username/var/cpanel/styled/current_style

If the style includes custom icons, run the sprite_generator utility.

After you apply a style that uses custom icons, run the following command, where mystyle represents the style name:

/usr/local/cpanel/bin/sprite_generator --theme paper_lantern --style mystyle

The /usr/local/cpanel/bin/sprite_generator utility integrates your icons into the new icon set.

Troubleshoot custom styles.

If you experience problems after you apply a custom style, read our Troubleshoot Custom Styles documentation.