- pm.max_children (the most PHP workers that can run at once) is the setting that matters most.
- Work it out with arithmetic: RAM available to PHP divided by the average memory one PHP process really uses.
- Too low and requests queue, causing 502 and 504 errors. Too high and the server runs out of memory.
- Measure real process size with
ps. memory_limit is a ceiling, not a usage figure. max_children reachedin the log is the clearest sign of a pool that is too small.
How do I calculate the right max_children?
PHP-FPM is the service that runs PHP for your web server, using a pool of worker processes. To tune it, set pm.max_children: the RAM left for PHP divided by the average size of one PHP process, rounded down. The common mistakes are guessing the process size and forgetting the database needs memory too.
# Average resident memory per PHP-FPM process, in MB
ps -ylC php-fpm8.3 --sort:rss | awk 'NR>1 {sum+=$8; n++} END {printf "avg %.0f MB across %d procs\n", sum/n/1024, n}'
# Total and available memory
free -m
# What everything else is using
ps -eo rss,comm --sort=-rss | head -15ps -ylC php-fpm --sort:rss if the program name has no version number.| Step | Example figure |
|---|---|
| Total RAM | 4096 MB |
| Reserve for MariaDB | 1024 MB |
| Reserve for Nginx, the OS and headroom | 768 MB |
| Available for PHP | 2304 MB |
| Measured average process size | 80 MB |
| max_children = 2304 / 80 | 28 |
Round down and leave headroom. 28 is a sound number on this machine; 50 is not.
memory_limit is not process size
A memory_limit of 256M is the point at which PHP stops a script, not what each worker uses. A typical WordPress request uses 40 to 100 MB, so sizing from memory_limit gives a number about three times too small.
Which process manager should I use?
PHP-FPM offers three modes. dynamic suits nearly every website: it keeps some workers ready and adds more under load. ondemand starts workers only when a request arrives, which suits several small sites sharing a server. static keeps every worker running all the time, and only makes sense for one busy site on its own machine.
| Mode | Behaviour | Use when |
|---|---|---|
| dynamic | Keeps spare workers ready, scales up under load | A normal site: the default choice |
| ondemand | Starts workers per request, kills them when idle | Many low-traffic sites on one server |
| static | All workers running all the time | One busy site with memory to spare |
If you are unsure, use dynamic. It is safe at almost any traffic level.
[example]
user = www-data
group = www-data
listen = /run/php/php8.3-fpm-example.sock
listen.owner = www-data
listen.group = www-data
pm = dynamic
pm.max_children = 28 ; the calculated ceiling
pm.start_servers = 7 ; 25% of max_children
pm.min_spare_servers = 4 ; never fewer ready workers than this
pm.max_spare_servers = 10 ; kill idle workers above this
pm.max_requests = 500 ; recycle a worker after 500 requests
; Log any request that takes longer than 10 seconds, with a stack trace
request_slowlog_timeout = 10s
slowlog = /var/log/php-fpm/example-slow.log
; Hard stop for a runaway request
request_terminate_timeout = 60s
; Status endpoint, restricted to localhost by the web server
pm.status_path = /fpm-statuspm.max_requests = 500 replaces each worker after 500 requests. That limits the damage when a plugin you do not control slowly leaks memory, at almost no cost.
How do I know max_children is too low?
PHP-FPM tells you in plain English in its log. It is the most useful line in PHP-FPM tuning, and most people never look for it.
# The definitive signal
sudo grep -i 'max_children' /var/log/php8.3-fpm.log
# Example output:
# WARNING: [pool example] server reached pm.max_children setting (20),
# consider raising it
# Follow it live during a traffic peak
sudo tail -f /var/log/php8.3-fpm.log
# How many workers are running right now
pgrep -c php-fpm| Symptom | Usually means |
|---|---|
| 502 Bad Gateway under load | No worker free: max_children too low, or workers stuck |
| 504 Gateway Timeout | A request ran longer than the proxy timeout |
| Site fine at 2am, slow at 2pm | Capacity, not code: workers run out at peak |
| Out of memory, processes killed | max_children too high for the RAM available |
| Slow but no errors | Not PHP-FPM. Look at the database or an external API |
Rows one and four are opposite failures of the same setting, which is why guessing is risky in both directions.
Raising max_children can make things worse
If the server is near its memory limit, more workers make the kernel kill processes to free RAM. It usually picks the database, because that is the largest. Check with dmesg -T | grep -i oom. If you see kills, lower max_children instead.
How do I use the PHP-FPM status page?
The status page shows how many requests are waiting and how many workers are busy, so tuning becomes reading a number. Make it reachable from the server itself only.
location ~ ^/fpm-status$ {
access_log off;
allow 127.0.0.1;
deny all;
fastcgi_pass unix:/run/php/php8.3-fpm-example.sock;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}curl -s http://127.0.0.1/fpm-status
# pool: example
# active processes: 12
# idle processes: 8
# total processes: 20
# max active processes: 24
# max children reached: 3 <-- this should be 0
# listen queue: 0 <-- this should be 0
# max listen queue: 18 <-- requests HAVE queued
# slow requests: 4
# Watch it during a peak
watch -n 2 'curl -s http://127.0.0.1/fpm-status'max children reached and max listen queue above zero are the two numbers that justify raising max_children.| Field | Healthy | Action if not |
|---|---|---|
| listen queue | 0 | Requests are waiting: raise max_children if RAM allows |
| max children reached | 0 | Anything above 0 means the ceiling was hit |
| max active processes | Below max_children | If it equals max_children you have no headroom left |
| slow requests | Near 0 | Read the slowlog: this is application time, not capacity |
Slow requests are a different problem from queued ones, and more workers will not help.
What else is worth tuning?
OPcache is the most valuable setting outside the pool. It keeps compiled PHP code in memory so files are not re-read and re-compiled on every request. On WordPress it typically removes about a third of the CPU work for a few lines of config.
opcache.enable=1
opcache.memory_consumption=256 ; MB of shared memory for bytecode
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000 ; WordPress plus plugins easily exceeds 10000
opcache.revalidate_freq=60 ; check for changed files every 60s
opcache.save_comments=1 ; some frameworks need docblocks at runtime
opcache.validate_timestamps=1 ; set to 0 only with a deploy-time cache resetLeave the JIT alone
OPcache's JIT helps number-heavy code, but a web request spends its time waiting on the database and disk. It has also caused memory faults on PHP 8.3, so we keep it off across our platform.
- Set request_terminate_timeout a little above Nginx's
fastcgi_read_timeout, so PHP stops a runaway script instead of leaving a stuck worker after the proxy gives up. - Use one pool per site, each with its own user and socket, so one site's runaway loop cannot take every worker.
- Run a current PHP version. Each release since 7.4 has run the same code faster. PHP versions for WordPress covers upgrading safely.
- Cache in front of PHP before you tune PHP. A page served from an Nginx reverse proxy cache uses no worker at all, which beats any pool setting.
If tuning pools is not how you want to spend your time, managed hosting takes it off your hands. On G7Cloud each site has its own PHP inside its own container, with the worker count worked out from the site's memory, OPcache on and the JIT off. See how our WordPress hosting performs.
Frequently asked questions
What should pm.max_children be set to?
The RAM available to PHP divided by the average size of one PHP-FPM process. Measure that size with ps -ylC php-fpm8.3 --sort:rss rather than assuming it, and first subtract what the database and web server need. A 4 GB server running MariaDB usually lands between 20 and 30.
Why does PHP-FPM return 502 Bad Gateway under load?
Usually because every worker is busy and new requests have nowhere to go. Look for "server reached pm.max_children setting" in the PHP-FPM log. If it is there, raise max_children, but only if you have the memory, or the kernel starts killing processes instead.
Should I use dynamic, ondemand or static process management?
dynamic for a normal website. ondemand when several low-traffic sites share one server, since idle sites then use nothing. static only for one busy site on its own machine, where you want every worker ready and have the RAM for it.
Does increasing max_children make my site faster?
Only if requests were queueing. It adds capacity, not speed: each request takes as long as before. If pages are slow with no queue and no max_children warnings, the bottleneck is the application or database, and more workers will not help.
What is pm.max_requests for?
It replaces a worker after that many requests, which limits memory leaks in code you do not control. 500 to 1000 is a sensible range, and the occasional restart costs almost nothing.
Should I enable the OPcache JIT for WordPress?
No. A WordPress request spends its time on the database and disk, so the JIT gains very little, and it has caused memory faults on PHP 8.3. Keep OPcache on and the JIT off.
About G7Cloud Engineering
Articles written by the engineers who build and run G7Cloud: UK managed hosting and the AI Website Builder. We write about what we operate every day: containers, backups, databases, and the small-business websites that run on them.
More about G7Cloud →