Enable and tune PHP-FPM in cPanel

PHP-FPM runs PHP in a pool of worker processes for each domain. It is faster than the old CGI handlers and lets you control exactly how many PHP processes a site may start. This guide shows how to enable PHP-FPM in WHM, size each pool for your VPS memory, and read the warnings that tell you a pool is too small.

Before you start

• cPanel & WHM on your VPS and root access to WHM and SSH.
• The domain uses an EasyApache 4 PHP version (ea-php81, ea-php83 and so on). Check in WHM » Software » MultiPHP Manager.
• Rough memory figures. Run free -m to see total RAM, and keep room for MySQL, Exim and the OS.

Enable PHP-FPM for domains

1. In WHM, open Software » MultiPHP Manager.
2. On the User Domain Settings tab, find the domain.
3. Switch the PHP-FPM toggle on. WHM builds a pool for that domain and reloads the service.

To make PHP-FPM the default for new accounts, open the System Settings tab and turn on the PHP-FPM default option there.

To enable it for many domains at once, tick them in the list and use the bulk PHP-FPM action at the top of the table.

Understand the pool settings

Click Edit PHP-FPM next to a domain (or set the defaults in System Settings). The three main fields are:

• Max Children: the most PHP processes this domain may run at once. When all are busy, new requests wait in a queue.
• Process Idle Timeout: seconds an idle process lives before it is stopped. cPanel's documented default is 10.
• Max Requests: how many requests one process serves before it is replaced. This limits slow memory leaks.

cPanel's defaults are deliberately small so that many accounts fit on one server. A busy single site usually needs more children than the default.

Size Max Children for your RAM

The rule is simple: Max Children × average process size must fit in the RAM you can spare for PHP.

Find the average size of a running PHP-FPM process for a version:

ps -eo rss,cmd | grep '[p]hp-fpm: pool' | awk '{sum+=$1; n++} END {if (n) printf "%d processes, average %.0f MB\n", n, sum/n/1024}'

Example output:

12 processes, average 68 MB

If you can give PHP about 1,500 MB and each process averages 70 MB, a safe total is around 20 children across all busy sites. Split that between domains according to traffic.

1. Click Edit PHP-FPM for the domain.
2. Set Max Children to your figure, for example 10.
3. Leave Max Requests at a few hundred if you suspect a plugin leaks memory.
4. Click Update.

Where cPanel stores pool settings

WHM writes per-domain choices to a YAML file and generates the real pool file from it:

• User overrides: /var/cpanel/userdata/USER/example.com.php-fpm.yaml
• Generated pools: /opt/cpanel/ea-php83/root/etc/php-fpm.d/example.com.conf

Do not edit the generated .conf file. It is rebuilt and your change is lost. If you edit the YAML file by hand, rebuild afterwards:

/usr/local/cpanel/scripts/php_fpm_config --rebuild
/scripts/restartsrv_apache_php_fpm

Check it works

Confirm the pool exists and processes are running:

ls /opt/cpanel/ea-php83/root/etc/php-fpm.d/
systemctl status ea-php83-php-fpm --no-pager

Then create a test file with <?php echo php_sapi_name; in the document root and open it. It should print fpm-fcgi. Delete the file afterwards.

Fix "max_children reached" warnings

The PHP-FPM error log for each version is in:

tail -n 50 /opt/cpanel/ea-php83/root/usr/var/log/php-fpm/error.log

A line like this means the pool hit its limit and visitors waited:

WARNING: [pool example_com] server reached max_children setting (5), consider raising it

Work through these steps in order:

1. Check memory first. If free -m shows little available RAM, raising Max Children will cause swapping. Find the slow pages instead, or move to a larger plan.
2. Look for slow requests. Long database queries or slow external API calls keep processes busy. Check the site's slow query log and plugins.
3. Raise Max Children in small steps, for example from 5 to 10, and watch the log and memory for a day.
4. Block bad bots that hammer search or login pages, which tie up every child at once.

Troubleshooting

• 503 Service Unavailable after enabling: the pool failed to start. Check the version's error.log and run /usr/local/cpanel/scripts/php_fpm_config --rebuild.
• Settings revert: you edited a generated .conf file. Use WHM or the YAML override instead.
• Server swaps under load: total possible PHP memory is larger than RAM. Lower Max Children on quiet sites.
• php_value lines in .htaccess cause 500 errors: PHP-FPM ignores Apache PHP directives. Move them to the MultiPHP INI Editor.

Next steps

• Pair PHP-FPM with a threaded Apache: switch Apache MPM to event in cPanel.
• Watch the effect on load: check server status and load in WHM.