Installing the Latest Versions of PHP on Raspberry Pi OS

In this guide, we will show you how you can install the latest versions of PHP without upgrading your version of Raspberry Pi OS.

PHP is the building block for a vast majority of web applications, and we use it for several of our Raspberry Pi projects.

Raspberry Pi OS Trixie already includes PHP 8.4 and receives security updates with the rest of your system. For most projects, this is the version you should use.

You only need this guide if a program you want to run requires a newer version of PHP than your operating system provides. To work around this, you can add a third-party repository that provides newer PHP versions, such as PHP 8.5.

Ondřej Surý maintains the repository for these PHP packages and is a well-respected contributor to the PHP community.

Please note that adding a third-party repository means trusting it with your whole system, as its packages are installed with full root access. We will set it up so your Raspberry Pi keeps using Raspberry Pi OS’s packages wherever they exist and only uses newer PHP versions from this repository.

Equipment

Below is a list of the equipment you may need when adding this third-party PHP repository on your Raspberry Pi.

Recommended

• Raspberry Pi Amazon
• Micro SD Card Amazon
• Power Supply Amazon
• Ethernet Cable Amazon or Wi-Fi Amazon

Optional

• HDMI Cable Amazon
• USB Keyboard Amazon
• USB Mouse Amazon
• Raspberry Pi Case Amazon

This tutorial was tested on a Raspberry Pi 5 running the latest version of Raspberry Pi OS Trixie.

Adding the 3rd Party PHP Repository

Adding a new repository in Raspberry Pi OS is straightforward, but it must be done from the terminal.

These steps also work on Ubuntu. Ondřej used to provide PHP for Ubuntu through a separate PPA, but he is moving it to this same repository, and the PPA has no packages for Ubuntu 26.04. Please note that Ubuntu 26.04 already comes with PHP 8.5, so you will only need this repository once a newer PHP version is released.

We need to download the GPG key and add the repository as a source for the package manager.

1. Before proceeding, we need to ensure the lsb-release package is installed on Raspberry Pi OS. This package allows us to quickly get the details we need when setting up the PHP repository.

For our first step, we need to update the package list by using the command below.

sudo apt updateCopy

2. Once the package list has finished updating, run the following command to install the lsb-release and curl packages.

sudo apt install -y lsb-release curlCopy

3. To use any third-party repository within Raspberry Pi OS, you need to provide its signing key. This key verifies that the packages you install actually come from that repository.

Ondřej provides this key as a package. By installing the key this way, your Raspberry Pi will get a new key automatically whenever he renews it. Download and install this package by running the following two commands.

curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb
sudo dpkg -i /tmp/debsuryorg-archive-keyring.debCopy

The first command downloads the key package to the /tmp folder. The second command installs it, which saves the key to /usr/share/keyrings/debsuryorg-archive-keyring.gpg.

4. Once the key has been saved to your Raspberry Pi, we can create a new source file that points to the repository.

Use the following one-liner to create this source file with the link to the repository.

echo "deb [signed-by=/usr/share/keyrings/debsuryorg-archive-keyring.gpg] https://packages.sury.org/php/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/sury-php.listCopy

Within this line, you can see that we point to the GPG key that we saved earlier. The “signed-by” text tells APT that it should verify the contents of this repository against the provided key.

If you followed an older version of this guide, this line replaces the one you added back then. You can also delete the old key file by running sudo rm /usr/share/keyrings/suryphp-archive-keyring.gpg.

5. Next, we will tell APT to only use this repository for packages that Raspberry Pi OS does not provide itself. Without this, the repository’s versions of packages such as “php-common” and “libgd3” would replace the ones that come with Raspberry Pi OS.

Begin writing a new APT preferences file by using the following command.

sudo nano /etc/apt/preferences.d/sury-phpCopy

6. Within this file, type in the following lines.

Package: *
Pin: origin packages.sury.org
Pin-Priority: 100Copy

These lines give every package from this repository a priority of 100, lower than the 500 that Raspberry Pi OS’s own packages have. When both have a package, APT will always pick Raspberry Pi OS’s version, so it will only install packages from this repository that Raspberry Pi OS does not have, such as PHP 8.5.

Once done, save and quit by pressing CTRL + X, then Y, followed by ENTER.

7. Since we made changes to the APT package sources, we must perform an update of the package lists.

Running an update requests new package lists from all sources. This will make APT aware of the packages being provided by our new PHP repository.

sudo apt updateCopy

Once the update completes, you can install newer versions of PHP than the one that comes with Raspberry Pi OS.

Raspberry Pi OS’s PHP packages block versions older than PHP 8.4, so with this setup, the repository is only used for newer versions.

Installing PHP 8.5 on a Raspberry Pi

To show you that this repository is working, we will be installing PHP 8.5 on our Raspberry Pi. This version of PHP is not available in Raspberry Pi OS Trixie, so this will only work if this repository has been added to the sources list.

1. To test this, we will install the command-line version of PHP 8.5 on our Raspberry Pi. You can install this on the device by running the following command in the terminal.

sudo apt install -y php8.5-cliCopy

When you install extensions for this version of PHP, always use the package names with the version in them, such as php8.5-mbstring. The names without a version, such as php-mbstring, are for Raspberry Pi OS’s own PHP 8.4.

2. If you see no errors, then you have successfully installed PHP 8.5 on your Raspberry Pi. We can verify it’s working by running a tiny PHP script.

Start by creating this simple PHP script using the following command in the terminal.

echo "<?php echo 'Hello World';" > test.phpCopy

This script is super simple and will echo the string “Hello World” to the command line when it is executed.

3. With this script created, you can use PHP 8.5 to run it by using the following command on your device.

php8.5 test.phpCopy

If PHP 8.5 has been successfully installed on your Pi, you should now see the text “Hello World” appear in the terminal.

Switching Between PHP Versions

Installing PHP 8.5 does not remove the version of PHP that comes with Raspberry Pi OS. Both can be installed side by side, and each has its own command, such as php8.4 and php8.5. However, the php command and your web server will only use one of them.

1. To see which version the php command currently runs, use the following command.

php -vCopy

This will most likely show PHP 8.5, as the php command uses the newest version of PHP that is installed. It will only still show PHP 8.4 if you have installed Raspberry Pi OS’s php-cli package.

This means that any PHP scripts you run from the terminal or a cron job will now use PHP 8.5. If they need extensions, such as php8.5-mysql, install them, or switch the php command back to PHP 8.4 by using the next step.

2. You can change which version of PHP the php command uses by running the following command.

sudo update-alternatives --config phpCopy

This command lists every version of PHP on your Raspberry Pi. Type in the number next to /usr/bin/php8.5 and press ENTER to switch to PHP 8.5.

There are 2 choices for the alternative php (providing /usr/bin/php).

  Selection    Path             Priority   Status
------------------------------------------------------------
* 0            /usr/bin/php8.5   85        auto mode
  1            /usr/bin/php8.4   84        manual mode
  2            /usr/bin/php8.5   85        manual mode

Press <enter> to keep the current choice[*], or type selection number:Copy

To go back to Raspberry Pi OS’s own PHP, run the same command again and pick /usr/bin/php8.4.

3. Your web server does not use the php command, so it will keep using the same version of PHP until you change it. How you do this depends on how your web server runs PHP. Before switching, install the PHP 8.5 version of every extension your website needs, such as php8.5-mysql.

If you use Apache with its PHP module, as in our Apache guide, install the PHP 8.5 module, disable the PHP 8.4 module, and enable the new one by running the following commands.

sudo apt install -y libapache2-mod-php8.5
sudo a2dismod php8.4
sudo a2enmod php8.5
sudo systemctl restart apache2Copy

To go back to PHP 8.4, run the last three commands again with php8.4 and php8.5 swapped.

4. If your web server uses PHP-FPM, as our NGINX, Lighttpd and Caddy guides do, install PHP-FPM 8.5 together with the extensions your website needs in a single command. For example, the following command installs the same extensions as our Lighttpd guide.

sudo apt install -y php8.5-fpm php8.5-mbstring php8.5-mysql php8.5-curl php8.5-gd php8.5-zip php8.5-xmlCopy

A web server that connects to /run/php/php-fpm.sock will start using PHP 8.5 as soon as it is installed. You can choose which version this connects to with the following command, picking /run/php/php8.4-fpm.sock to go back to PHP 8.4.

sudo update-alternatives --config php-fpm.sockCopy

If your web server’s configuration names a version of PHP instead, such as php8.4-fpm.sock, change it to php8.5-fpm.sock and restart your web server.

Removing the PHP Repository

If you no longer need the newer version of PHP, you can remove it along with the repository. Your Raspberry Pi will then go back to only using the PHP that comes with Raspberry Pi OS.

1. First, if you switched the php command or your web server to PHP 8.5, switch them back to PHP 8.4 by following the steps in the previous section.

If your web server uses PHP-FPM and stops working after the next step, run sudo systemctl restart php8.4-fpm to point it back to PHP 8.4.

2. Next, remove PHP 8.5 by running the following command. Every PHP 8.5 package depends on php8.5-common, so removing it also removes the rest of PHP 8.5, along with its configuration files.

sudo apt purge -y php8.5-commonCopy

3. Now remove the repository’s source and preferences files, then its key package, using the following two commands.

sudo rm /etc/apt/sources.list.d/sury-php.list /etc/apt/preferences.d/sury-php
sudo apt purge -y debsuryorg-archive-keyringCopy

4. Lastly, update the package list so that APT no longer looks for packages from the repository.

sudo apt updateCopy

If you followed an older version of this guide, also remove PHP 8.1 by running sudo apt purge -y php8.1-common before step 3. The repository may have replaced some of Raspberry Pi OS’s own packages too, which will no longer receive updates. Once you have finished the steps above, you can list these packages by using the following command.

apt list --installed 2>/dev/null | grep -F ",local]"Copy

Put each package it lists back to Raspberry Pi OS’s version by running the following command, replacing <PACKAGE> with the package’s name.

sudo apt install -y --allow-downgrades <PACKAGE>/trixieCopy

Conclusion

Installing a newer version of PHP than the one that comes with Raspberry Pi OS is relatively straightforward.

Thanks to the package repository provided by Ondřej Surý, you can run the latest releases of PHP on your Raspberry Pi while the rest of Raspberry Pi OS stays as it is.

If you have had any issues installing your required PHP version, feel free to leave a comment below.

Be sure to check out some of our excellent PHP-driven projects, such as our Nextcloud guide or our Joomla tutorial.