How to Configure PHP-FPM with NGINX

Introduction

PHP-FPM pinch NGINX is the modular measurement to tally PHP connected Nginx. Nginx has no built-in PHP module for illustration Apache’s mod_php. Nginx serves fixed files and forwards .php requests to PHP-FPM complete FastCGI, usually done a Unix socket.

In this tutorial you instal PHP-FPM connected Ubuntu, create a dedicated pool, link Nginx pinch fastcgi_pass, trial the stack, and troubleshoot 502 errors.

Version note: Commands were checked against Ubuntu 22.04 LTS (Jammy), 24.04 LTS (Noble Numbat), and 26.04 LTS (Resolute Raccoon) pinch PHP from the default Ubuntu repositories. Default PHP versions per release: 8.1 connected 22.04, 8.3 connected 24.04, and 8.5 connected 26.04. Confirm your host with lsb_release -rs and php -v earlier you edit paths aliases work names.

Ubuntu LTS type reference

Use this array to switch package names, sockets, and config paths connected your server. Default PHP versions travel from the Ubuntu archive. See php-fpm connected Noble (24.04) and php-fpm connected Resolute (26.04).

Pool configs unrecorded nether /etc/php/<version>/fpm/pool.d/. On 24.04 and 26.04, sudo apt instal php-fpm installs the default metapackage for that release.

The step-by-step examples beneath usage PHP 8.1 connected Ubuntu 22.04. Replace 8.1 with 8.3 aliases 8.5 erstwhile you activity connected 24.04 aliases 26.04.

Key takeaways

• Nginx does not execute PHP. PHP-FPM runs worker processes and receives requests done FastCGI.
• Install the FPM package for your PHP version: php8.1-fpm connected 22.04, php8.3-fpm connected 24.04, aliases php8.5-fpm connected 26.04.
• Point Nginx astatine the excavation socket pinch fastcgi_pass unix:/run/php/php8.1-fpm.sock (swap 8.1 for 8.3 aliases 8.5 arsenic needed) inside a location ~ \.php$ block.
• Pool files unrecorded successful /etc/php/<version>/fpm/pool.d/. Each [pool_name] section controls user, socket path, and process head settings.
• A 502 Bad Gateway usually intends a socket mismatch, stopped PHP-FPM service, or incorrect record permissions connected the socket.
• Unix sockets activity for Nginx and PHP-FPM connected the aforesaid server. TCP larboard 9000 fits containers aliases distant FPM hosts.
• Separate pools fto you tally different sites nether different Unix users and PHP versions.

Prerequisites

Before you start, corroborate you have:

• An Ubuntu 22.04, 24.04, aliases 26.04 LTS server pinch SSH entree arsenic a sudo-enabled user.
• Nginx installed. On 22.04, follow How To Install Nginx connected Ubuntu 22.04. On 24.04 aliases 26.04, tally sudo apt instal nginx aft sudo apt update.
• PHP installed, aliases scheme to instal the LEMP stack. The afloat 22.04 walkthrough is How To Install Linux, Nginx, MySQL, PHP (LEMP stack) connected Ubuntu 22.04. The aforesaid package names use connected newer LTS releases erstwhile you usage the version table above.

What is PHP-FPM?

PHP-FPM (FastCGI Process Manager) is simply a PHP SAPI that manages a excavation of worker processes. A maestro process listens connected a socket aliases TCP port. Worker processes execute PHP scripts and return output to the web server.

PHP-FPM vs mod_php

How PHP-FPM and Nginx activity together

1. A browser requests https://example.com/index.php.
2. Nginx matches location ~ \.php$ and passes the petition to PHP-FPM through FastCGI.
3. PHP-FPM assigns an idle worker aliases spawns 1 based connected excavation settings.
4. The worker runs the book and sends the consequence backmost to Nginx.
5. Nginx returns the consequence to the client.

For the charismatic Nginx integration notes, see Nginx connected Unix systems.

Step 1: Install PHP-FPM

Check your Ubuntu and PHP versions:

lsb_release -rs php -v

Install the FPM package that matches your release:

On 24.04 and 26.04 you besides person the action to tally sudo apt instal php-fpm, which installs the default PHP FPM metapackage for that release.

The 22.04 illustration continues below:

sudo apt update sudo apt install php8.1-fpm

Enable and commencement the service. Swap the work sanction connected 24.04 (php8.3-fpm) or 26.04 (php8.5-fpm):

sudo systemctl enable php8.1-fpm sudo systemctl commencement php8.1-fpm sudo systemctl position php8.1-fpm

You should spot progressive (running). Confirm the default socket:

ls -l /run/php/php8.1-fpm.sock

Expected socket paths by release:

Step 2: Configure a PHP-FPM pool

The default excavation record is /etc/php/8.1/fpm/pool.d/www.conf connected Ubuntu 22.04. On 24.04 usage /etc/php/8.3/fpm/pool.d/www.conf. On 26.04 use /etc/php/8.5/fpm/pool.d/www.conf. For a azygous site, editing www is enough. For aggregate apps, create 1 excavation per site.

This illustration creates a excavation named wordpress_site nether a dedicated user.

Create the personification and group:

sudo groupadd wordpress_user sudo useradd -g wordpress_user -d /var/www/wordpress -s /usr/sbin/nologin wordpress_user

Create the excavation file:

sudo nano /etc/php/8.1/fpm/pool.d/wordpress_pool.conf

Add the pursuing configuration. Keep the PHP type accordant successful the socket path:

[wordpress_site] user = wordpress_user group = wordpress_user listen = /run/php/php8.1-fpm-wordpress.sock listen.owner = www-data listen.group = www-data listen.mode = 0660 php_admin_value[disable_functions] = exec,passthru,shell_exec,system php_admin_flag[allow_url_fopen] = off pm = dynamic pm.max_children = 20 pm.start_servers = 4 pm.min_spare_servers = 2 pm.max_spare_servers = 8 pm.max_requests = 500

Pool directives explained:

Reload PHP-FPM aft changes. Use the work sanction for your PHP version:

sudo systemctl reload php8.1-fpm

On 24.04 tally sudo systemctl reload php8.3-fpm. On 26.04 run sudo systemctl reload php8.5-fpm.

Verify the caller socket exists:

ls -l /run/php/php8.1-fpm-wordpress.sock

Step 3: Configure Nginx for PHP-FPM

Create aliases edit a server artifact successful /etc/nginx/sites-available/. Point fastcgi_pass astatine the excavation socket from Step 2.

server { listen 80; server_name example.com; root /var/www/wordpress; index index.php index.html; access_log /var/log/nginx/example.com-access.log; error_log /var/log/nginx/example.com-error.log; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php8.1-fpm-wordpress.sock; } location ~ /\.ht { deny all; } }

snippets/fastcgi-php.conf ships pinch the Ubuntu Nginx package. It sets fastcgi_split_path_info and SCRIPT_FILENAME using $document_root$fastcgi_script_name.

Enable the tract and trial the config:

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx

NGINX Server Block

Set ownership connected the web guidelines truthful the excavation personification sounds the files:

sudo chown -R wordpress_user:wordpress_user /var/www/wordpress

For Nginx troubleshooting patterns, see Nginx Essentials.

Step 4: Test the PHP-FPM and Nginx setup

Create a trial record successful the web root:

echo '<?php phpinfo(); ?>' | sudo tee /var/www/wordpress/info.php

Open http://example.com/info.php successful a browser. Confirm $_SERVER['USER'] shows wordpress_user, which intends Nginx routed the petition done your custom pool.

NGINX PHP-FPM Testing

Delete info.php aft testing. phpinfo() exposes server specifications to anyone who visits the URL.

sudo rm /var/www/wordpress/info.php

Socket vs TCP for fastcgi_pass

On 24.04 usage unix:/run/php/php8.3-fpm.sock. On 26.04 use unix:/run/php/php8.5-fpm.sock.

Socket illustration (default pool):

fastcgi_pass unix:/run/php/php8.1-fpm.sock;

TCP illustration (set perceive = 127.0.0.1:9000 successful the excavation record first):

fastcgi_pass 127.0.0.1:9000;

Fix 502 Bad Gateway errors

Nginx returns 502 Bad Gateway erstwhile PHP-FPM is unreachable aliases fails to respond. Work done these checks successful order.

1. Confirm PHP-FPM is running. On 22.04:

sudo systemctl position php8.1-fpm

On 24.04 cheque php8.3-fpm. On 26.04 cheque php8.5-fpm.

2. Match the socket path successful Nginx and the excavation perceive directive. Swap 8.1 for your PHP version:

grep -r fastcgi_pass /etc/nginx/sites-enabled/ grep perceive /etc/php/8.1/fpm/pool.d/*.conf

3. Check socket permissions. Nginx runs arsenic www-data and needs read/write access to the socket:

ls -l /run/php/

4. Read the logs:

sudo tail -f /var/log/nginx/error.log sudo journalctl -u php8.1-fpm -f

On 24.04 switch the portion pinch php8.3-fpm. On 26.04 usage php8.5-fpm.

5. Raise timeouts if scripts tally long. Add wrong the location ~ \.php$ block:

fastcgi_read_timeout 300;

Tune PHP-FPM performance

Start pinch blimpish p.m. values and raise them based connected RAM and traffic. Each PHP worker uses memory. A unsmooth starting constituent connected a 2 GB Droplet:

pm = dynamic pm.max_children = 10 pm.start_servers = 2 pm.min_spare_servers = 1 pm.max_spare_servers = 4 pm.max_requests = 500

Enable the built-in position page for monitoring. Add to the excavation file:

pm.status_path = /fpm-status

Add a matching Nginx location (restrict entree to your IP):

location ~ ^/fpm-status$ { access_log off; allow 127.0.0.1; deny all; include fastcgi_params; fastcgi_pass unix:/run/php/php8.1-fpm.sock; }

For WordPress connected the aforesaid stack, follow How To Install WordPress pinch LEMP connected Ubuntu 22.04. The Nginx and PHP-FPM wiring is the aforesaid connected 24.04 and 26.04 erstwhile you usage the correct socket way from the type table.

Ubuntu 24.04 and 26.04 LTS notes

Ubuntu 24.04 LTS (Noble) and 26.04 LTS (Resolute) usage the aforesaid Nginx layout arsenic 22.04: server blocks successful /etc/nginx/sites-available/, the snippets/fastcgi-php.conf include, and www-data arsenic the Nginx user.

Differences to watch connected newer LTS releases:

DigitalOcean LEMP tutorials presently target Ubuntu 22.04. The instal and config steps successful this guideline use to 24.04 and 26.04 erstwhile you substitute package names, work units, and socket paths from the type table. I person not re-tested each bid connected a caller 26.04 image successful this refresh, truthful run php -v and ls -l /run/php/ connected your Droplet to corroborate paths earlier you go live.

FAQs

1. Does NGINX usage PHP-FPM?

Yes. Nginx has nary embedded PHP engine. For .php files, Nginx forwards the request to PHP-FPM done FastCGI. You ligament the relationship pinch fastcgi_pass in a location ~ \.php$ block.

2. How do you instal NGINX and PHP-FPM connected Ubuntu?

Install Nginx, past the FPM package for your LTS release:

Enable some services (example for 22.04):

sudo apt update sudo systemctl enable --now nginx php8.1-fpm

Add a server artifact pinch fastcgi_pass pointing astatine the socket for your PHP version. The afloat LEMP walkthrough for 22.04 is in How To Install Linux, Nginx, MySQL, PHP (LEMP stack) connected Ubuntu 22.04.

3. What does PHP-FPM do?

PHP-FPM is simply a process head for PHP. A maestro process controls worker processes that execute scripts. Pools specify sockets, users, and scaling rules. PHP-FPM is the required PHP handler erstwhile you usage Nginx.

4. What causes a 502 correction pinch PHP-FPM?

A 502 intends Nginx could not get a valid consequence from PHP-FPM. Common causes include a stopped PHP-FPM work (php8.1-fpm, php8.3-fpm, or php8.5-fpm), a incorrect socket way successful fastcgi_pass, socket support errors, or PHP crashes successful the worker. Check /var/log/nginx/error.log and journalctl -u php8.1-fpm (swap the portion sanction for your PHP version).

5. Is PHP-FPM basal pinch NGINX?

Yes, if you want Nginx to tally PHP. Without PHP-FPM (or different FastCGI PHP handler), Nginx serves only fixed files. PHP-FPM besides separates PHP representation from the web server process, which is why astir accumulation Nginx stacks usage it instead of older CGI methods.

Conclusion

You installed PHP-FPM, created a civilization pool, connected Nginx with fastcgi_pass, and learned really to trial the stack and hole 502 errors. Separate pools springiness you per-site users, sockets, and worker limits.

For aggregate PHP versions connected 1 host, see multiple PHP versions connected Ubuntu. For HTTPS, follow How To Secure Nginx pinch Let’s Encrypt connected Ubuntu 22.04.

What’s next

Keep building pinch these PHP tutorials and Nginx tutorials:

• How To Install Linux, Nginx, MySQL, PHP (LEMP stack) connected Ubuntu 22.04 (swap PHP package names per the type array connected 24.04 aliases 26.04)
• How To Install WordPress pinch LEMP connected Ubuntu 22.04
• How To Install PHP 8.1 connected Ubuntu 22.04
• Nginx Essentials: Installation and Configuration Troubleshooting
• Initial Server Setup pinch Ubuntu

Deploy from GitHub with DigitalOcean App Platform or tally the afloat stack connected a Droplet. Choose an Ubuntu 26.04 LTS image erstwhile you create the VM if you want the newest LTS with PHP 8.5 successful the default repositories.