Skip to content
Servers

How to Upgrade PHP on Ubuntu With Nginx and PHP-FPM (LEMP)

In this article11 sections

On a LEMP server, which is Linux, Nginx, MySQL or MariaDB and PHP, the PHP part runs as a separate service called PHP-FPM, and Nginx hands every PHP request to it over a socket. That design makes an upgrade clean: you install the new PHP-FPM beside the old one, point Nginx at the new socket, and test, without touching the web server’s other settings. The old version stays installed until you are sure, so the rollback is a one-line change. This guide upgrades PHP on Ubuntu 24.04 with Nginx and PHP-FPM, from the packages and extensions, to the pool settings, the socket, the command-line version, and the checks that tell you it worked.

It applies to a SiteHarbour VPS, where you have root access, and to any Ubuntu server. The commands assume a user with sudo rights, and the examples move from PHP 8.3 to PHP 8.4.

Why the distribution package may not be what you want

Ubuntu 24.04 ships one PHP version in its default repositories, which is 8.3 at the time of its release, and it keeps that version for the life of the release, applying security fixes. That is a stable choice. If you need a newer version, or several versions side by side, the usual route is the repository maintained by Ondřej Surý, which provides current PHP builds for Ubuntu. Add it only if you need it, and know that you are then taking PHP updates from that source, not from Ubuntu.

Before you start

  • Snapshot or back up. A VPS snapshot, plus a database dump, gives you a complete way back. The database side is in how to back up MariaDB and PostgreSQL on a VPS.
  • List what runs now. Record the current version, the loaded extensions and the pool settings, because the new version starts with defaults:
php -v
php -m | sort > ~/php-modules-before.txt
sudo cp -a /etc/php/8.3 ~/php-8.3-config-backup

Expected: the version line, a saved list of extensions, and a copy of the configuration. These files are your reference for everything that follows.

Step 1: Add the repository and install the new PHP-FPM

sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt update

Then install the FPM service and the extensions your site needs. Compare the list with ~/php-modules-before.txt, and install the matching packages for the new version:

sudo apt install -y php8.4-fpm php8.4-cli php8.4-common php8.4-mysql php8.4-curl \
  php8.4-mbstring php8.4-xml php8.4-zip php8.4-gd php8.4-intl php8.4-opcache php8.4-bcmath

Expected: the packages install, and a new service named php8.4-fpm starts. Check it, and check that the old one is still running:

systemctl is-active php8.3-fpm php8.4-fpm
ls -l /run/php/

Expected: both services active, and two sockets, php8.3-fpm.sock and php8.4-fpm.sock. Both versions now run side by side. Nginx still sends traffic to the old one.

Step 2: Carry the settings across

The new version has its own configuration under /etc/php/8.4/. Compare it with the old one, and copy over only the values you changed, not the whole file, because defaults can change between versions:

diff -u /etc/php/8.3/fpm/php.ini /etc/php/8.4/fpm/php.ini | less
diff -u /etc/php/8.3/fpm/pool.d/www.conf /etc/php/8.4/fpm/pool.d/www.conf | less

Values that are usually changed on purpose are memory_limit, upload_max_filesize, post_max_size, max_execution_time, and in the pool file pm.max_children, pm.start_servers and pm.max_requests. Size the pool from memory you measure on your own server, as shown in how to size Apache event MPM and PHP-FPM from measurements, and not from a copied number. For a small server, how to optimize PHP-FPM workers on limited RAM shows the safe approach.

Check the OPcache settings too, since OPcache gives most of the speed gain. Make sure it is enabled in /etc/php/8.4/fpm/php.ini, and set a memory value that fits your code base. Check the pool file for its user and group, which should match the user that owns the site’s files.

Test the configuration of the new service before you use it:

sudo php-fpm8.4 -t

Expected: a line that says the configuration test is successful. Fix anything it reports first.

Step 3: Point Nginx at the new socket

Open the server block for the site, usually under /etc/nginx/sites-available/. Find the line that passes PHP requests and change the socket name:

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.4-fpm.sock;
}

Test the Nginx configuration, then reload. A reload keeps existing connections, so visitors do not notice:

sudo nginx -t && sudo systemctl reload nginx

Expected: the test passes, and the site continues to load. If you host several sites, change one server block at a time. That lets you move the least important site first, and it keeps a rollback for the rest.

Step 4: Confirm the site runs on the new version

Create a temporary file in the site’s web root, open it in a browser, and delete it:

echo '<?php echo PHP_VERSION;' | sudo tee /var/www/example/public/version-check.php
curl -s https://example.com/version-check.php
sudo rm /var/www/example/public/version-check.php

Expected: the new version number, such as 8.4.x. Then check the new pool is doing the work, and not the old one:

sudo tail -n 20 /var/log/php8.4-fpm.log
sudo journalctl -u php8.4-fpm --since "10 min ago" --no-pager

Expected: no errors. Check the Nginx error log for upstream errors, which would show a wrong socket path, and see how to fix 502 Bad Gateway on Nginx if you get one.

Step 5: Make the command line use the new version

The web server and the command line are separate. The php command still runs the old version until you change it. Set the default and check:

sudo update-alternatives --set php /usr/bin/php8.4
php -v

Expected: the new version. Cron jobs, Composer, Artisan and WP-CLI use this version. For any job that names a PHP binary directly, change the path to /usr/bin/php8.4. A queue worker or scheduler run by Supervisor or systemd keeps running the old code until you restart it, so restart those services as well.

Step 6: Watch, then clean up

Leave both versions in place for a few days. Check the PHP-FPM log and the application’s own log each day. When the site has run cleanly across a full week, including any weekly or monthly jobs, stop and disable the old service, and only after that remove its packages:

sudo systemctl disable --now php8.3-fpm
sudo apt remove 'php8.3*'

Keep the configuration backup from the start of this guide for another month. Removing the old packages too early removes your rollback.

Rollback

Until you remove the old version, rolling back is one line: set fastcgi_pass back to php8.3-fpm.sock, run sudo nginx -t && sudo systemctl reload nginx, and switch the command line back with update-alternatives. Test the site afterwards. A rollback does not undo database changes that the new version caused, so restore the database dump if the application ran a migration.

Common mistakes

  • Installing the FPM package but not the extensions. The site then fails with undefined function errors.
  • Copying the old php.ini over the new one. Defaults change between versions. Copy only your own values.
  • Forgetting the command-line version. Cron and Artisan keep running the old PHP.
  • Not restarting queue workers. They hold the old code in memory.
  • Removing the old version at once. You lose the instant rollback.

Frequently asked questions

Can I run two PHP versions for two sites?

Yes. Each server block names its own socket, so one site can use 8.3 and another 8.4 at the same time.

Do I need to restart Nginx?

A reload is enough. It re-reads the configuration without dropping connections.

Is the Surý repository safe to use?

It is widely used on Ubuntu and Debian servers. You take PHP updates from it instead of from Ubuntu, so keep the server updated and review what the update changes.

What if a new version is not available for my Ubuntu release?

Upgrade the Ubuntu release first, or run PHP in a container, as described in how to upgrade PHP in Docker containers.

On a LEMP server, the upgrade is an install, a settings comparison, a socket change and a reload, with the old version still available as your rollback. Install the new FPM with the extensions you used, carry over only your own settings, point Nginx at the new socket, switch the command line and the workers, and clean up only after a clean week. Keep the server patched too: the real-world example of why is in how to fix and mitigate the PHP2Shell vulnerability on your server.

Want this done for you? If you would rather have an engineer plan and carry out the work on your own site, you can hire the author through the Upwork profile of Munaf Sheikh.

Share this guide