How to restart php-fpm inside a docker container?

How to restart php-fpm inside a docker container?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How to Restart php-fpm Inside a Docker Container

When deploying applications using PHP-FPM behind Nginx or Apache, configuration changes often require a restart of the FastCGI process manager. In a standard Linux environment, this is trivial: you execute systemctl restart php-fpm or service php7-fpm restart. However, inside a Docker container running on the official php:5.6-fpm image (or any FPM-based variant), the process hierarchy is different. The PHP-FPM master process is not a system service; it is a foreground process owned by the container itself. To reload configuration or restart the pool without killing the application, you must interact directly with the process manager via its built-in control socket.

The most robust method to restart php-fpm from within the container is by using the php-fpm command-line interface, which communicates with the master process through a local Unix socket. This approach avoids the need for external orchestration tools like Docker Compose or docker exec unless you prefer them. The standard way to invoke this is by sending specific signals to the master process.

You can restart the entire PHP-FPM pool by running the following command inside your container:

php-fpm -R

The -R flag tells the PHP-FPM master process to send a SIGUSR1 signal to all child worker processes and then reload the configuration files. This is functionally equivalent to restarting the service on a host system, but it happens gracefully within the container's PID namespace. If you are using Nginx or Apache as a reverse proxy, this restart will take effect immediately because the web server maintains its own connection pool settings (e.g., fastcgi_connect_timeout), while PHP-FPM re-initializes its worker processes.

Alternatively, if your goal is simply to reload configuration without restarting workers—which is useful for changing values like pm.max_children or memory limits—you can use:

php-fpm -D -t

Wait, that syntax is incorrect for reloading config directly via CLI in older versions. The correct approach for a full restart (which clears existing worker connections) remains -R. For a true configuration reload without dropping active connections, you would send SIGUSR2 to the master process. However, the PHP-FPM CLI does not have a direct "reload only" flag that sends just SIGUSR2 while keeping workers alive in all versions of 5.6. The -R flag is generally preferred because it ensures a clean state after configuration changes.

If you prefer managing this from outside the container, you can use docker exec:

docker exec <container_name> php-fpm -R

This command executes the PHP-FPM binary inside the running container with root privileges (or the default user if configured correctly). It sends the restart signal to the process already running in the foreground. This method is essential when your development workflow involves frequent configuration tweaks, such as modifying php.ini or pool definitions in /usr/local/etc/php-fpm.d/www.conf.

One common pitfall is attempting to restart php-fpm by killing and starting the container. While this works, it causes downtime for all connected clients and resets any session state held by PHP-FPM workers. Using -R ensures that connections are handled gracefully by Nginx, which may reuse existing TCP connections depending on its keepalive settings, though PHP-FPM workers will be recreated.

Another consideration is the php-fpm daemon mode. In the official image, the entrypoint runs php-fpm in the foreground to allow Docker to manage the container lifecycle. Executing -D (daemonize) is not recommended inside containers because it detaches from the process stream, potentially causing Docker to think the application has exited prematurely if an error occurs later. Always run php-fpm without the -d flag when using Docker unless you have specific logging setups that require separation of concerns.

If you are managing multiple pools (e.g., www, api), you can target a specific pool by specifying its name:

php-fpm -R www

However, this syntax is not universally supported in all versions of PHP-FPM and may require checking the version-specific documentation. In most cases, restarting the global process with -R is safer and covers all defined pools.

For production environments where you need to monitor restarts or handle errors more gracefully, consider integrating health checks that verify the socket status before sending restart signals. This prevents race conditions where a restart signal is sent before the previous workers have fully exited.

Our network