When a PHP site on Nginx suddenly returns 502 Bad Gateway, or slows to a crawl every time a promotion goes out, the cause is very often not the PHP code. It is PHP-FPM, the process manager that sits between the web server and the application, still running on the settings it was installed with. On Debian and Ubuntu that means a single pool with a maximum of five worker processes, which is fine for a test server and far too small for a busy shop. This article explains how PHP-FPM works and how to configure it for a real workload, based on what we see when we take over PHP servers from other teams.
What PHP-FPM Is and Why Nginx Needs It
Nginx cannot run PHP. When a request for a .php file arrives, Nginx passes it over FastCGI to a separate service and waits for the answer. PHP-FPM, short for FastCGI Process Manager, is that service. It starts a master process that keeps a group of PHP worker processes ready. Each worker takes one request at a time, runs the script, sends the response back to Nginx, and then waits for the next one.
Apache can work differently. With mod_php, PHP is loaded inside every Apache process, which only works with the older prefork model and means even requests for images carry the memory of a PHP interpreter. Modern Apache setups use the event model with PHP-FPM through proxy_fcgi, the same split as Nginx. Either way, the number of PHP requests a server can handle at the same moment is the number of PHP-FPM workers, and that is the number most worth getting right.
Pools, Workers, and Where the Files Live
PHP-FPM is organised into pools. A pool is a group of workers with its own Linux user, its own socket, its own limits, and its own PHP settings. A fresh install has one pool called www. On Debian and Ubuntu, the files are in a folder per PHP version:
- /etc/php/8.4/fpm/php-fpm.conf holds global settings such as the error log and emergency restart rules.
- /etc/php/8.4/fpm/pool.d/ holds one file per pool. The default is www.conf.
- /etc/php/8.4/fpm/php.ini is the php.ini for web requests. The command line uses /etc/php/8.4/cli/php.ini, a different file, which is why a setting can work in php artisan and not on the website.
- /run/php/php8.4-fpm.sock is the default socket that Nginx connects to.
- The service is called php8.4-fpm, so the commands are systemctl reload php8.4-fpm and journalctl -u php8.4-fpm.
On Red Hat based systems the layout is /etc/php-fpm.conf and /etc/php-fpm.d/ instead, and in the official Docker php images the pool files are under /usr/local/etc/php-fpm.d/. The settings themselves are the same everywhere.
Static, Dynamic, or Ondemand
The pm setting decides how a pool starts and stops workers. All three modes share the same hard limit, pm.max_children. They only differ in how many workers are kept running while the server is quiet.
| Mode | How it behaves | Good for | Downside |
|---|---|---|---|
| static | Always runs exactly pm.max_children workers | A dedicated server or container for one busy application | Memory stays reserved even at night when there is no traffic |
| dynamic | Keeps a number of idle workers between pm.min_spare_servers and pm.max_spare_servers, and starts more up to the limit | Most single-application VPS setups, and the Debian default | Four numbers to tune, and bad combinations cause constant start and stop |
| ondemand | Starts workers only when requests arrive and stops them after pm.process_idle_timeout | Servers hosting many small sites, where most pools are idle most of the time | The first request after a quiet period waits for a new worker to start |
For a server that runs one main application, we usually choose dynamic with generous spare servers, or static if the server is dedicated to the app and memory is not shared with a database. For a server with twenty small company websites, ondemand keeps idle sites from holding memory that a busy one could use.
Calculating pm.max_children
pm.max_children is the most important number in PHP-FPM. Set it too low and requests queue up behind busy workers while the CPU sits idle. Set it too high and a traffic spike starts more workers than memory can hold, the server begins to swap, and everything slows down at once, including the database. The right value comes from memory, not from a number found online.
- 1Let the application run under normal traffic for a while, so the workers have handled real pages rather than just the home page.
- 2Measure the average memory per worker. On Ubuntu, ps --no-headers -o rss -C php-fpm8.4 lists the resident memory of each process in kilobytes. Ignore the master process, take the average of the rest, and note the largest value as well. A typical Laravel or WordPress worker uses somewhere between 40 and 100 MB, but your own number is the one that counts.
- 3Work out how much memory PHP can have. Start from total RAM and subtract the operating system, the database if it runs on the same server, Redis, and anything else, plus a safety margin of 10 to 20 percent.
- 4Divide that memory by the average worker size and round down. For example, on an 8 GB VPS with MySQL using 2.5 GB, the system and Redis about 1 GB, and a 1 GB margin, there are 3.5 GB left. At 70 MB per worker that gives 50, so pm.max_children = 50.
- 5For dynamic mode, start with pm.start_servers and pm.min_spare_servers at about a quarter of the limit and pm.max_spare_servers at about half, then adjust from the status page described below.
Do not calculate with memory_limit from php.ini. memory_limit is the most a single request may use before PHP stops it, such as 256 MB, not what a worker normally uses. Dividing RAM by memory_limit gives a number far too small. It is a ceiling that protects you from one runaway request, while the average is what decides how many workers fit.
The number of CPU cores matters less than people expect. Most web requests spend much of their time waiting for the database or an external API, and a waiting worker uses no CPU. That is why 50 workers on a 4 core server is normal for an ordinary web application. The exception is CPU-heavy work such as generating PDFs or resizing images inside the request, where more workers than cores only adds waiting. That kind of work belongs in a queue anyway.
Other Settings Worth Changing
| Setting | Debian and Ubuntu default | What we usually set |
|---|---|---|
| pm.max_children | 5 | Calculated from memory as above |
| pm.max_requests | 0, so workers are never recycled | 500 to 1000, which limits slow memory leaks in extensions or code |
| request_terminate_timeout | 0, so no limit | Slightly above the longest request you accept, for example 60s |
| request_slowlog_timeout and slowlog | Off | 5s, with a log file per pool, to get a stack trace of slow requests |
| pm.status_path and ping.path | Off | /fpm-status and /fpm-ping, reachable only from localhost or monitoring |
| catch_workers_output | no | yes, so errors written to stderr reach the FPM log |
request_terminate_timeout deserves a note. Many people assume max_execution_time in php.ini stops slow requests, but on Linux it only counts time spent running PHP code. Time spent waiting for a database query, an HTTP call, or a file read is not counted, so a request stuck on a slow API can hold a worker for minutes. request_terminate_timeout is measured on the wall clock and is the setting that actually frees the worker.
The slow log is one of the most useful tools PHP-FPM has and one of the least used. With request_slowlog_timeout = 5s, every request that runs longer than five seconds writes a backtrace to the slow log showing the exact function it was in at that moment. When a site is slow and nobody knows why, a few hours of slow log usually points to the query or API call responsible.
One Pool per Site
Many servers run every site in the default www pool as the www-data user. That works until one site gets a traffic spike and uses all the workers, so every other site on the server returns 502 as well. It is also a security problem: if one WordPress site is compromised, the attacker runs code as www-data and can read the configuration files, including database passwords, of every other site.
Giving each site its own pool solves both. Create a Linux user per site, copy www.conf to a new file such as shop.conf, and change these lines:
- [shop] at the top, which is the pool name used in logs and the status page.
- user = shop and group = shop, so PHP runs as the site's own user and can only read that site's files.
- listen = /run/php/php8.4-fpm-shop.sock, a separate socket per pool.
- listen.owner = www-data and listen.group = www-data, so Nginx can still connect to the socket.
- pm.max_children and the other pm values sized for this site alone.
- php_admin_value[open_basedir] = /var/www/shop:/tmp and php_admin_value[memory_limit] = 256M for limits the application cannot override at runtime.
Then point the Nginx server block for that site to the new socket with fastcgi_pass unix:/run/php/php8.4-fpm-shop.sock, test the configuration with php-fpm8.4 -t and nginx -t, and reload both services. Remember that the total of all pm.max_children values on a server must still fit in memory. With many pools, ondemand helps a lot here.
Several PHP Versions on One Server
PHP has no single tool like nvm for Node.js, and on a server it does not need one. PHP-FPM already separates versions cleanly. On Ubuntu, Ondřej Surý's PPA, and his packages.sury.org repository for Debian, provide every supported PHP version side by side. Install php8.2-fpm, php8.4-fpm, and php8.5-fpm, and each runs as its own service with its own folder in /etc/php and its own socket. An old site stays on 8.2 by pointing its Nginx block to the 8.2 socket, while a new one uses 8.5.
- Extensions are per version. Installing php8.4-mysql does nothing for 8.2, so install php8.2-mysql, php8.2-mbstring, php8.2-xml, and the rest for each version a site uses.
- The php command line is a separate choice. update-alternatives --set php /usr/bin/php8.4 changes the default php, which affects cron jobs, artisan commands, and Composer. For a site on a different version, call the binary directly, for example php8.2 artisan schedule:run.
- Plan the end of each version. PHP 8.2 gets its last security fixes on 31 December 2026, and PHP 8.3 a year later. A server with an 8.2 pool after that date runs an unpatched PHP for that site.
- Check the version the website really uses, not just php -v. A simple way is a temporary file in that site's folder that prints PHP_VERSION, deleted right after, or checking which socket the Nginx block uses. After a security update such as the PHP2Shell fixes in October, every php-fpm service has to be restarted, not only the default one.
Common Errors and What They Usually Mean
| What you see | Usual cause | Where to look or what to change |
|---|---|---|
| 502 Bad Gateway with connect() to unix:/run/php/... failed (2: No such file or directory) in the Nginx log | PHP-FPM is not running, or Nginx points to the socket of a version that is not installed | systemctl status php8.4-fpm, then check that the socket path in fastcgi_pass matches the pool |
| 502 with (13: Permission denied) | Nginx is not allowed to open the socket | Set listen.owner and listen.group in the pool to the user Nginx runs as |
| server reached pm.max_children setting in the FPM log, and pages hang or return 502 | All workers are busy and requests are queuing | Raise pm.max_children if memory allows, otherwise find the slow requests with the slow log |
| 504 Gateway Timeout after exactly 60 seconds | A request took longer than Nginx is willing to wait, set by fastcgi_read_timeout | Fix the slow request, or move the work to a queue. Raising the timeout only hides it |
| Primary script unknown, or a blank page with File not found | SCRIPT_FILENAME points to a path the pool cannot see, or open_basedir blocks it | Check root and fastcgi_param SCRIPT_FILENAME in Nginx and the pool's user and open_basedir |
| Workers killed by the kernel and Out of memory in dmesg | pm.max_children is higher than the server can hold | Recalculate from real worker memory and lower the limit |
Watch the Status Page
With pm.status_path enabled and allowed only from localhost in Nginx, curl http://localhost/fpm-status shows the state of a pool at that moment. Three numbers matter most. active processes shows how many workers are busy right now. max children reached counts how many times the pool hit its limit since it started, and should stay at zero or rise only rarely. listen queue shows requests waiting for a free worker, and anything above zero for more than a moment means users are waiting. Uptime Kuma, Zabbix, Netdata, and the Prometheus php-fpm exporter can all read this page and alert on it.
Security Basics
- Listen on a Unix socket, or on 127.0.0.1 if it must be TCP. A PHP-FPM port such as 9000 open to the internet lets anyone send FastCGI requests directly and, with crafted parameters, run PHP code on the server.
- Keep Nginx from passing files that do not exist to PHP. On Debian and Ubuntu, include snippets/fastcgi-php.conf, which already does this, or add try_files $uri =404 in the PHP location. Without it, an uploaded file such as avatar.jpg/x.php can be executed as PHP on some setups.
- Leave security.limit_extensions at .php so FPM refuses to run other file types.
- Never make the status page public. It reveals request URLs, client addresses, and how busy the server is.
- Run each site in its own pool and user, as described above, so one compromised site cannot read another site's files.
PHP-FPM in Docker, and the Alternatives
The official php:8.4-fpm image runs PHP-FPM listening on port 9000 inside the container, usually paired with a separate Nginx container that connects to it over the internal Docker network. Everything above still applies. The pool file is in /usr/local/etc/php-fpm.d/www.conf, and pm.max_children should be calculated from the memory limit of the container, not the whole host. A container with a 1 GB limit and the default of five workers rarely runs out of memory, but it also rarely serves more than five requests at a time.
PHP-FPM is not the only way to run PHP any more. FrankenPHP, now maintained under The PHP Foundation, and Laravel Octane with Swoole or RoadRunner keep the application loaded in memory between requests, which can make a framework-heavy application noticeably faster. They also change the rules, because state left in memory by one request can leak into the next. For most PHP applications, a well-configured PHP-FPM is still the simplest choice, and the place to start before looking at anything else.
A Short Checklist
- 1Check which pools run on the server and which PHP version each site uses. Plan to move anything on PHP 8.2 before the end of 2026, and note that PHP 8.6 is scheduled for 19 November 2026.
- 2Measure real worker memory and set pm.max_children from it, leaving room for the database and a margin.
- 3Set pm.max_requests, request_terminate_timeout, and the slow log in every pool.
- 4Give each site its own pool, user, and socket.
- 5Enable the status page for localhost only and connect it to your monitoring.
- 6After every PHP security release, restart every php-fpm service on the server and confirm the version each site reports.
Most of these changes take an afternoon and cost nothing, yet they are often the difference between a server that falls over during a campaign and one that handles it quietly. If your PHP or Laravel servers keep returning 502 under load, or you would like someone to review the setup, our managed service team can take it on, and our Laravel training covers deployment and PHP-FPM for teams that want to run it themselves.
Key takeaways
- PHP-FPM runs the PHP workers behind Nginx, and the number of workers is the number of PHP requests a server can handle at once.
- The Debian and Ubuntu default of five workers is too small for most production sites.
- Calculate pm.max_children from the real average memory per worker and the RAM left after the database, not from memory_limit.
- Set pm.max_requests, request_terminate_timeout, and a slow log. On Linux, max_execution_time does not count time spent waiting for I/O.
- Give each site its own pool, user, and socket, and use separate php8.x-fpm services to run several PHP versions side by side.
- Keep PHP-FPM on a Unix socket or localhost, keep the status page private, and restart every FPM service after a PHP security update.


