Skip to content
Servers

How to Upgrade PHP on Ubuntu With Apache: mod_php and PHP-FPM

In this article11 sections

On a LAMP server, which is Linux, Apache, MySQL or MariaDB and PHP, there are two ways PHP can run. The older way loads PHP into Apache as a module, called mod_php. The current way runs PHP as a separate PHP-FPM service that Apache talks to over a socket. The two need different steps to upgrade, so the first job is to find out which one your server uses. This guide covers both on Ubuntu 24.04: how to tell them apart, how to move from one PHP version to the next with each, and how to move from mod_php to PHP-FPM while you are at it, which is the better setup for most sites.

It applies to a SiteHarbour VPS or any Ubuntu server with root access. The examples move from PHP 8.3 to PHP 8.4, and every command assumes a user with sudo rights.

Step 0: Find out how PHP runs on your server

Check which Apache modules and configuration files are active:

apache2ctl -M | grep -i "php\|proxy_fcgi\|mpm"
ls /etc/apache2/conf-enabled | grep -i php

Read the result:

  • A line with php_module or php8_module means mod_php. Apache loads PHP itself, and runs with the prefork MPM.
  • A line with proxy_fcgi_module, a file such as php8.3-fpm.conf in conf-enabled, and the event MPM means PHP-FPM.

The MPM matters. mod_php needs prefork, which handles each connection with a full process and uses more memory. PHP-FPM works with the event MPM, which handles many more connections with less memory. The sizing numbers for the event MPM are in how to size Apache event MPM and PHP-FPM from measurements.

Before you start

  • Snapshot or back up the server, and dump the databases.
  • Record the current state:
php -v
php -m | sort > ~/php-modules-before.txt
sudo cp -a /etc/php/8.3 ~/php-8.3-config-backup
sudo cp -a /etc/apache2 ~/apache2-config-backup

Expected: the version line, and two backup folders. You will use them for comparison and for the rollback.

Step 1: Add the repository

Ubuntu 24.04 ships PHP 8.3. For a newer version, add the repository maintained by Ondřej Surý, which provides current PHP builds for Ubuntu:

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

You then receive PHP updates from that source. Review updates before you apply them on a production server.

Path A: Upgrade with mod_php

Install the Apache module for the new version, plus the CLI and the extensions that match your old list:

sudo apt install -y libapache2-mod-php8.4 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

Only one PHP module can be active at a time. Switch from the old module to the new one, test the configuration and restart Apache:

sudo a2dismod php8.3
sudo a2enmod php8.4
sudo apache2ctl configtest
sudo systemctl restart apache2

Expected: Syntax OK from the test, and the site loading. mod_php needs a restart, not a reload, so connections are dropped for a moment. Do it at a quiet hour. Then switch the command line version:

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

mod_php reads its settings from /etc/php/8.4/apache2/php.ini, which is a separate file from the CLI one at /etc/php/8.4/cli/php.ini. Copy your own values, such as memory_limit and upload limits, into the Apache one, and not the whole old file.

Path B: Upgrade with PHP-FPM

Install the new FPM service and the extensions, beside the old one:

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
sudo php-fpm8.4 -t

Expected: the configuration test is successful. Compare the pool and php.ini with the old version and copy across only the values you changed, as in how to upgrade PHP on Ubuntu with Nginx and PHP-FPM. Then switch Apache’s FPM configuration from the old version to the new one:

sudo a2disconf php8.3-fpm
sudo a2enconf php8.4-fpm
sudo apache2ctl configtest
sudo systemctl reload apache2

Expected: Syntax OK, and the site continues to load without a restart. If you run several virtual hosts, each can name its own handler. Inside a virtual host, a line such as SetHandler "proxy:unix:/run/php/php8.4-fpm.sock|fcgi://localhost" inside a FilesMatch block for \.php$ selects the version for that site only, which lets you move one site at a time.

Path C: Move from mod_php to PHP-FPM during the upgrade

If you found mod_php in Step 0, upgrading is a good moment to move to PHP-FPM, since it uses less memory and handles more concurrent visitors. The order matters:

sudo apt install -y php8.4-fpm
sudo a2dismod php8.3 mpm_prefork
sudo a2enmod mpm_event proxy_fcgi setenvif
sudo a2enconf php8.4-fpm
sudo apache2ctl configtest
sudo systemctl restart apache2

Expected: Syntax OK and a working site. This step replaces the MPM, so it needs a restart. Test every site, because some older applications assume mod_php, for example by reading settings from .htaccess with php_value lines. Those lines do not work under PHP-FPM and cause a 500 error. Move them to a .user.ini file or to the pool configuration. Start with the pool sizing from how to optimize PHP-FPM workers on limited RAM if the server has little memory.

Step 2: Confirm the version

echo '<?php echo PHP_VERSION;' | sudo tee /var/www/html/version-check.php
curl -s http://localhost/version-check.php
sudo rm /var/www/html/version-check.php

Expected: the new version. Check the logs after a few hours and the next day:

sudo tail -n 30 /var/log/apache2/error.log
sudo tail -n 30 /var/log/php8.4-fpm.log

The second file exists only on the FPM paths. Look for Fatal error, then Warning and Deprecated. The usual causes and fixes are in how to fix common errors after a PHP upgrade.

Step 3: Update cron, workers and permissions

  • Cron. Replace PHP paths with /usr/bin/php8.4.
  • Queue workers. Restart Supervisor or systemd services that run PHP, because they hold the old code.
  • Session files. Check that the session directory is writable by the new pool’s user, or users are logged out on the first request.

Rollback

For mod_php, run sudo a2dismod php8.4 && sudo a2enmod php8.3 && sudo systemctl restart apache2. For PHP-FPM, run sudo a2disconf php8.4-fpm && sudo a2enconf php8.3-fpm && sudo systemctl reload apache2. Keep the old packages until the site has run cleanly for a week. If the move also changed the MPM, restore the saved Apache configuration folder first.

Common mistakes

  • Enabling two PHP modules. Only one mod_php version can be active.
  • Moving to PHP-FPM and leaving php_value lines in .htaccess. They cause 500 errors under FPM.
  • Editing the CLI php.ini and expecting the website to change. Apache and FPM have their own files.
  • Forgetting the extensions. The site fails on the first missing function.
  • Using a reload where a restart is needed. Changing modules or the MPM needs a full restart.

Frequently asked questions

Is PHP-FPM really better than mod_php?

For most sites, yes. It uses less memory per visitor, allows the event MPM, and isolates each site’s pool. mod_php remains simple, which suits a very small server.

Can I run two PHP versions on one Apache server?

Yes, with PHP-FPM. Each virtual host names its own socket. With mod_php you cannot, because only one module can be active.

Why does my site return 500 after switching to FPM?

Often php_value or php_flag lines in .htaccess. Remove them and set the values in .user.ini or the pool file.

Do I need to restart Apache after changing the PHP version with FPM?

A reload is enough when you only change the handler configuration.

First find out whether Apache runs PHP as a module or through FPM, then follow the matching path. With mod_php, swap the module and restart. With PHP-FPM, install beside the old version, change the handler and reload. If you are on mod_php, consider moving to PHP-FPM and the event MPM while you upgrade. Test, watch the logs, and keep the old version until a clean week has passed. For a hosting setup that handles this for you, see SiteHarbour VPS hosting, where the stack is installed and secured before handover.

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