VPS Snaps

How to upgrade PHP 8.2 to 8.4 on Debian and Ubuntu with a rollback plan

PHP 8.2 gets its last security fixes on December 31, 2026. PHP 8.4 is supported until December 31, 2028, so it is the sensible target for a server you do not want to touch again soon. On Debian and Ubuntu you do not have to replace 8.2 in one go: both versions install side by side, each with its own PHP-FPM service, so you can move a site to 8.4 and move it back by changing one line. These steps are for Debian 12 and Ubuntu 22.04 and 24.04, with PHP-FPM behind Nginx or Apache, or Apache with mod_php.

Back up before you start

Switching PHP versions does not touch your database or uploaded files, but plugins and frameworks sometimes run migrations on the first request under a new version. Back up three things:

  • A snapshot of the whole server at your provider. Hetzner and DigitalOcean recommend powering off for a consistent snapshot.
  • A database dump stored off the server. See mysqldump backups or pg_dump backups.
  • Your PHP and web server configuration, so you can compare or put back any setting.
Terminal
sudo tar czf /root/pre-php84-$(date +%F).tar.gz /etc/php /etc/nginx
php -v
dpkg --list | awk '/^ii/ && $2 ~ /^php8\.2/ {print $2}' > php82-packages.txt
cat php82-packages.txt

Use /etc/apache2 instead of /etc/nginx in the tar line if you run Apache. php82-packages.txt is the list of PHP 8.2 packages you have, such as php8.2-fpm, php8.2-mysql and php8.2-curl. You will install the same set for 8.4.

Rehearse on a copy of the server

The safest way to find out whether your app runs on PHP 8.4 is to do the whole upgrade on a temporary server built from the snapshot you just took. On Hetzner that is hcloud server create --name php84-test --type <server-type> --image <snapshot-id>, and on DigitalOcean doctl compute droplet create php84-test --image <snapshot-id> --size <size-slug> --region <region>.

To test the copy in a browser under your real domain, point the domain at the copy's IP on your own computer only, by adding a line to /etc/hosts on macOS or Linux:

/etc/hosts
<test-server-ip>  <your-domain>  www.<your-domain>

The copy has the same configuration as production. Disable its cron jobs, queue workers and outgoing email first, or it may send real emails, charge payments or write to shared services. Remove the /etc/hosts line and delete the test server when you are done.

Add the PHP 8.4 package repository

Debian 12 ships PHP 8.2 and Ubuntu 24.04 ships 8.3, so 8.4 comes from the community packages that php.net's download page points to: packages.sury.org on Debian and the ondrej/php PPA on Ubuntu. If php -v already shows a deb.sury.org build, the repository is set up and you can skip this step.

On Debian 12:

Terminal
sudo apt update
sudo apt install -y lsb-release ca-certificates curl
sudo curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb
sudo dpkg -i /tmp/debsuryorg-archive-keyring.deb
sudo tee /etc/apt/sources.list.d/php.sources <<EOF
Types: deb
URIs: https://packages.sury.org/php/
Suites: $(lsb_release -sc)
Components: main
Signed-By: /usr/share/keyrings/debsuryorg-archive-keyring.gpg
EOF
sudo apt update

On Ubuntu 22.04 or 24.04:

Terminal
sudo apt update
sudo apt install -y software-properties-common
sudo LC_ALL=C.UTF-8 add-apt-repository ppa:ondrej/php -y
sudo apt update

php.net notes that these builds come from a third party, include patches the PHP project does not control, and include a patch that adds telemetry to the Apache 2 and PHP-FPM modules. Read that note on php.net's download page before you decide.

Install PHP 8.4 beside 8.2

Turn your 8.2 package list into an 8.4 list and install it. Nothing about 8.2 changes, and your sites keep using it until you switch them.

Terminal
sed 's/^php8\.2/php8.4/' php82-packages.txt > php84-packages.txt
cat php84-packages.txt
sudo apt install $(cat php84-packages.txt)

If apt says it is unable to locate a package, remove that line from php84-packages.txt and look up its replacement with apt search php8.4. If you use Apache with mod_php, the list will not include the module because its name does not start with php8.2. Add libapache2-mod-php8.4 yourself.

Install php8.4-fpm and php8.4-cli by name rather than the bare php8.4 package on an Nginx server. The bare package needs a server API and apt can satisfy that by installing the Apache module, which can pull in Apache itself.

Terminal
php8.4 -v
php8.4 -m
systemctl status php8.4-fpm --no-pager
php -v

The last line matters. The plain php command is managed by update-alternatives, which in automatic mode picks the highest-priority version, so installing 8.4 can quietly move cron jobs and tools such as WP-CLI or Composer to 8.4. Pin it to 8.2 until you are ready:

Terminal
sudo update-alternatives --set php /usr/bin/php8.2

Carry your PHP settings across

Each version has its own configuration under /etc/php/<version>/. Anything you changed for 8.2, such as memory_limit, upload_max_filesize, post_max_size or a custom FPM pool, has to be made again for 8.4. Compare the active lines of the two php.ini files:

Terminal
diff <(grep -Ev '^\s*(;|$)' /etc/php/8.2/fpm/php.ini) <(grep -Ev '^\s*(;|$)' /etc/php/8.4/fpm/php.ini)
ls /etc/php/8.2/fpm/pool.d/ /etc/php/8.4/fpm/pool.d/
ls /etc/php/8.2/fpm/conf.d/ /etc/php/8.4/fpm/conf.d/

Some differences are just new defaults. Copy across the ones you set on purpose. If you have pool files other than www.conf, copy them into /etc/php/8.4/fpm/pool.d/ and change any listen socket path that contains 8.2, so the two versions do not fight over one socket. Then test the configuration and restart:

Terminal
sudo php-fpm8.4 -t
sudo systemctl restart php8.4-fpm

Check your code against PHP 8.4

Update your CMS, plugins, themes and Composer dependencies to versions that support PHP 8.4 before you switch. Then run a syntax check over your code with the 8.4 binary. It only catches syntax errors, not behaviour changes, but it is quick:

Terminal
find /var/www/<site> -name '*.php' -print0 | xargs -0 -n1 -P4 php8.4 -l | grep -v '^No syntax errors'

PHP 8.4 changes that commonly affect web apps, from the PHP manual's migration guide:

  • The E_STRICT error level was removed. Code that still references the constant gets a deprecation notice.
  • PDO MySQL attributes ATTR_AUTOCOMMIT, ATTR_EMULATE_PREPARES and MYSQL_ATTR_DIRECT_QUERY are now booleans instead of integers.
  • When a MySQL 8.0.24 or later server closes an idle connection, the error code is now 4031 instead of 2006. Retry logic that matches on 2006 needs updating.
  • The OPcache JIT defaults changed to opcache.jit=disable and opcache.jit_buffer_size=64M. If you enabled JIT only by setting a buffer size, set opcache.jit explicitly.

Switch the site to PHP 8.4

With Nginx and PHP-FPM, find the socket the site uses and point it at the 8.4 socket:

Terminal
grep -rn 'php8.2-fpm.sock' /etc/nginx/
sudo sed -i 's#/run/php/php8.2-fpm.sock#/run/php/php8.4-fpm.sock#' /etc/nginx/sites-available/<site>
sudo nginx -t && sudo systemctl reload nginx

With Apache and PHP-FPM, swap the enabled configuration. a2enconf and a2disconf create and remove symlinks in /etc/apache2/conf-enabled:

Terminal
sudo a2disconf php8.2-fpm
sudo a2enconf php8.4-fpm
sudo apache2ctl configtest && sudo systemctl reload apache2

With Apache and mod_php, swap the module instead:

Terminal
sudo a2dismod php8.2
sudo a2enmod php8.4
sudo systemctl restart apache2

Confirm which version is serving pages with a one-line check file, then delete it:

Terminal
echo '<?php echo PHP_VERSION;' | sudo tee /var/www/<site>/php-version-check.php
curl -s https://<your-domain>/php-version-check.php; echo
sudo rm /var/www/<site>/php-version-check.php

When the site works, move the command line and any cron jobs over too:

Terminal
sudo update-alternatives --set php /usr/bin/php8.4
sudo grep -rn 'php8.2' /etc/cron* /var/spool/cron 2>/dev/null

Never leave a file that prints PHP details on a public site. Delete the check file as soon as you have read the version.

Roll back in under a minute

PHP 8.2 is still installed and its FPM service is still running, so going back is the same change in reverse:

SetupSwitch back to 8.2
Nginx + PHP-FPMsudo sed -i 's#/run/php/php8.4-fpm.sock#/run/php/php8.2-fpm.sock#' /etc/nginx/sites-available/<site> then sudo nginx -t && sudo systemctl reload nginx
Apache + PHP-FPMsudo a2disconf php8.4-fpm && sudo a2enconf php8.2-fpm then sudo systemctl reload apache2
Apache + mod_phpsudo a2dismod php8.4 && sudo a2enmod php8.2 then sudo systemctl restart apache2
Command linesudo update-alternatives --set php /usr/bin/php8.2

If a plugin changed the database on its first run under 8.4 and 8.2 now fails on it, restore the database dump you took before you started. If the server itself is in a bad state, restore the snapshot. See the guides for Hetzner and DigitalOcean.

Remove PHP 8.2 and keep backups running

Give the new version a week or two of normal traffic. Then remove 8.2 so nothing falls back to it by accident:

Terminal
sudo apt purge $(cat php82-packages.txt)

apt purge deletes /etc/php/8.2 along with the packages. Keep the tarball you made at the start, and copy it off the server before you purge.

Your nightly backups should include /etc/php from now on, next to the database dump and site files. A crontab line that archives it each night:

crontab -e
30 2 * * * tar czf /var/backups/etc-php-$(date +\%F).tar.gz /etc/php

Check a backup restores by listing it and unpacking it somewhere harmless, then comparing a file you know:

Terminal
tar tzf /var/backups/etc-php-<YYYY-MM-DD>.tar.gz | head
mkdir -p /tmp/php-restore-test && tar xzf /var/backups/etc-php-<YYYY-MM-DD>.tar.gz -C /tmp/php-restore-test
diff /etc/php/8.4/fpm/php.ini /tmp/php-restore-test/etc/php/8.4/fpm/php.ini && echo 'restore matches'

Frequently asked questions

Should I upgrade to PHP 8.3 or 8.4?
PHP 8.3 gets security fixes until December 31, 2027 and 8.4 until December 31, 2028. If your app supports 8.4, it buys an extra year before the next upgrade. PHP 8.5 is supported until December 31, 2029 if your stack is ready for it.
Can PHP 8.2 and 8.4 run on the same server?
Yes. On Debian and Ubuntu each version has its own packages, its own /etc/php/<version> directory and its own FPM service and socket, so different sites can use different versions.
Why did php -v change after I installed 8.4?
The php command is managed by update-alternatives. In automatic mode it points at the highest-priority installed version. Use update-alternatives --set php /usr/bin/php8.2 to pin it until you are ready.
Do I need to back up anything for a PHP upgrade?
Yes. The upgrade itself is reversible, but plugins and frameworks can change the database on their first run under a new version. A snapshot and a database dump taken just before the switch let you undo that too.

How this was checked

Commands, limits and prices were checked against these official pages, on November 2, 2026: