Having to customize the php-fpm pool configuration of a new server, I wonder if it is possible / allowed / recommended to have a new pool file, which name goes alphabetically after the original one, which only has values that override the initial configuration.

The original configuration is in /etc/php/7.0/fpm/pool.d named www.conf.

It seems, according to the pages related to the installation, engineers modify directly the original (saving a copy of the initial values). E.g.

user www-data
group www-data
pm.max_children 2

gives after modification

user myapp         ; was www-data
group myapp        ; was www-data
pm.max_children 8  ; was 2

But it seems that could be a task to be repeated after the next upgrade of php-fpm (furthermore the configuration is in a 7.0 path, that's worrying).

Instead of modifying the original file, I would like to keep it unchanged, and add another one, say wwwmyapp.conf that would declare the same pool, and having only the values that have changed

in wwwmyapp.conf

[www]        ; same pool!
user myapp
group myapp
pm.max_children 8

in pool.d, list of files


since in php-fpm.conf all pool conf files are loaded, the values of wwwmyapp will be read after the ones of www ( in the same www pool ) and should override the first values.

  • It seems to work in a few tests and no error reported, but will it work all the time, and for all values?
  • Should we overwrite the config file directly instead?

Couldn't find an answer in any doc, even on php.net.

  • At least in Debian / Ubuntu based distributions, the upgrade process asks if it should keep the old configuration files or install upgraded ones from package. It will install the new configuration file with a suffix so one can check the changes that way. I assume other package managers have a similar feature. Therefore I think it is a matter of opinion. However, having too pool definitions with the same name doesn't sound like it would work in the future too. Commented Sep 27, 2016 at 18:24

3 Answers 3


Could not find an "official" confirmation from another source, but here is some outcome after doing some research:

Analyzing the source code of php7.0-fpm and more specifically fpm-conf.c, it appears that

  • the main configuration file php-fpm.conf is read first [ fpm_conf_load_ini_file() ],
  • all include directives are read in order, giving a list of files thanks to glob(),
  • each of the file is parsed by the same fpm_conf_load_ini_file(),
  • an entry in the file overwrites any previously set value,
  • any new include will have a recursive call to the includes processing function, and
  • the glob() function sorts names, by default (no GLOB_NOSORT option)

Thus we can assume - at least in this version but this is unlikely to change soon considering the present code - that it is safe to arrange the pool.d directory configuration files in alphabetical order ; any previously recorded value being overwritten by an entry with the same name read after.

We have a clean way to handle configuration files for php-fpm, keeping the distribution ones untouched, and adding custom files having name alphabetically greater than the packaged ones, that contain the few options that have to be changed.

  • 1
    +1 for not changing the default configuration. I always have troubles when I use that one for production environment because it gets reverted to defaults while upgrading. Commented Apr 16, 2018 at 12:27
  • global FPM overrides under pool.d are possigbe using [global] section. e.g. emergency_restart_threshold. Tested on php7.1-fpm ubuntu (server 18).
    – hrvoj3e
    Commented Jan 9, 2020 at 13:12
  • 2
    Also, because default pool name is www the only way to override is using pool.d filenames like wwwsomething or starting with x, y or z.
    – hrvoj3e
    Commented Jan 9, 2020 at 13:15
  • 2
    Thanks! I've named my file z-www-overrides.conf and it overidden [www] pool options!
    – IStranger
    Commented Apr 14, 2020 at 21:07
  • @hrvoj3e No, you can actually rename the default www.conf as you wish, something like 50-default.conf, then add your own files, like 10-before.conf and 70-after.conf.
    – Déjà vu
    Commented Oct 21, 2021 at 1:48

In case u have some file like php-overrides.ini you should copy it to


99 prefix is due to order of execution

  • conf.d overrides cannot override php-fpm.conf variables (only in pool.d/ under [global]) (note to future self)
    – hrvoj3e
    Commented Jan 9, 2020 at 13:19

Overriding [www] pool values through custom .conf files:

It is possible, and @breaking-not-so-bad explanation of how config files are loaded is great, I recommend you read it first.

But it is definitely worth emphasising the importance of config files naming (as it can be tricky):

As @hroj3e explained and @istranger exemplified in the comments above

  • If the default pool name is www the only way to override it is using pool.d filenames like wwwsomething or starting with x, y or z - @hroj3e
  • Named the filez-www-overrides.conf and it's overidden [www] pool options - @istranger

An example:

Creating a file /etc/php/7.0/fpm/conf.d/z-www-overrides.conf will override the settings in php-fpm.conf:

user myapp
group myapp
pm.max_children 8
  • Emphasising the importance of the naming convention and the example. As someone who sets up infrastructure every so often (and that tries to rely on copy-paste and light edits as much as possible), I felt I could have gone through the process faster by having that data available in a more digestible way, which is what I tried to do for others. However, not bringing brand new insights, I wanted to make as clear as possible that my reply is almost a TL;DR of yours Commented Oct 11, 2021 at 16:05

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .