How to install or upgrade to PHP 8.3 on Ubuntu and Debian

Published On12 Nov 2023

How to install or upgrade to PHP 8.3 on Debian and Ubuntu

PHP 8.3 is 2023's major new update to PHP. It brings nice new features such as typed class constants, a new set of Exceptions in DateTime extension, a new json_validate function, and a handful of new features, changes, and deprecations. As always, PHP 8.3 brings several bug fixes and improvements as well as performance improvements.

This article explains how to install PHP 8.3 on modern Debian systems and Ubuntu systems. Some of the most popular PECL extensions are also available to install in a similar way, which are listed in the Installing PECL Extensions section.

A similar guide is also available for Installing/Upgrading PHP 8.3 on RHEL/Fedora/CentOS Stream/Alma/Rocky Linux.

Quick-Start
- Install PHP 8.3 on Debian 10, 11, or 12
- Install PHP 8.3 on Ubuntu 20.04, 22.04, or 22.04
Detailed PHP 8.3 Installation Steps
Running PHP 8.3 Alongside Other Versions

Quick-Start

In the terminal as a sudo-capable user, run the following commands for Debian or Ubuntu. For detailed steps, go to the Detailed Installation/Upgrade guide.

Debian (10, 11, and 12)

# Save existing php package list to packages.txt file
sudo dpkg -l | grep php | tee packages.txt

# Add Ondrej's repo source and signing key along with dependencies
sudo apt install apt-transport-https
sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update

# Install new PHP 8.3 packages
sudo apt install php8.3 php8.3-cli php8.3-{bz2,curl,mbstring,intl}

# Install FPM OR Apache module
sudo apt install php8.3-fpm
# OR
# sudo apt install libapache2-mod-php8.3

# On Apache: Enable PHP 8.3 FPM
sudo a2enconf php8.3-fpm
# When upgrading from an older PHP version:
sudo a2disconf php8.2-fpm

# Remove old packages
sudo apt purge php8.2*

Ubuntu (20.04, 22.04, and 24.04)

## Save existing php package list to packages.txt file
sudo dpkg -l | grep php | tee packages.txt

# Add Ondrej's PPA
sudo add-apt-repository ppa:ondrej/php # Press enter when prompted.
sudo apt update

# Install new PHP 8.3 packages
sudo apt install php8.3 php8.3-cli php8.3-{bz2,curl,mbstring,intl}

# Install FPM OR Apache module
sudo apt install php8.3-fpm
# OR
# sudo apt install libapache2-mod-php8.2

# On Apache: Enable PHP 8.3 FPM
sudo a2enconf php8.3-fpm
# When upgrading from an older PHP version:
sudo a2disconf php8.2-fpm

## Remove old packages
sudo apt purge php8.2*

Detailed Installation/Upgrade guide

1. Prerequisites

None of the current Debian and Ubuntu versions include PHP 8.3 in their default software repositories. Prebuilt PHP packages are available from a repository maintained by Ondřej Surý, which this article uses. Packages in this repository follow the same package configuration, package names, and systemd configuration as the PHP packages provided by the OS software repositories.

This article focuses on Ubuntu 22.04 (Jammy), Ubuntu 20.04 (Focal), Ubuntu 24.04 (Noble), Debian 10 (Buster), Debian 11 (Bullseye), and Debian 12 (Bookworm).

Heads up: Potentially destructive actions ahead
The following actions are executed as sudo, and require that level of permissions to continue. The usual warnings when making any system-wide changes apply here as well. Make sure to backup the system and check the backups before continuing.
When upgrading, do not forget to migrate configuration to the new PHP version.

2. List and keep note of existing PHP packages

When upgrading an existing PHP version, the following command lists all packages installed with the word php in the package name, and saves it to a packages.txt file as well as printing it in the terminal.

This will be helpful to install the corresponding PHP 8.3 packages in the next steps.

This step is not necessary when installing PHP on a new system.

dpkg -l | grep php | tee packages.txt

3. Add `ondrej/php` repository

PHP 8.3 is not available to download from any of the current Debian or Ubuntu software repositories. Debian and Ubuntu software repositories maintained by Ondřej Surý contain the main PHP 8.3 packages and several popular PECL packages, and they are kept up to date.

On Ubuntu, the packages are only built on LTS versions. This step will fail on non-LTS Ubuntu versions such as Ubuntu 22.10.

The following commands add the repository to the list of software repositories, and runs apt update to fetch list of packages available from the new repository as well as existing repositories.

Debian

sudo apt install apt-transport-https
sudo curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update

Ubuntu

sudo add-apt-repository ppa:ondrej/php # Press enter when prompted.
sudo apt update

4. Install New PHP 8.3 Packages

With Ondrej's PHP repository added, PHP packages can now be installed with apt. All PHP 8.3 packages follow php8.3-XYZ pattern. These names match and override the PHP versions provided by the OS's own software repositories.

sudo apt install php8.3-common php8.3-cli php8.3-fpm php8.3-{curl,bz2,mbstring,intl}

The php8.3-common package is a meta-package that installs several PHP extensions. It is possible to selectively disable individual extensions later. PHP Core extensions such as Date, Phar, JSON, ctype, and random are always included. It is not necessary nor possible to install them as separate packages.
Instead of installing php8.3-common, it is also possible to install individual packages. Installing php8.3-common is roughly equivalent to installing all of the extensions as shown below:
```
apt install php8.3-{calendar,ctype,exif,ffi,fileinfo,ftp,gettext,iconv,pdo,phar,posix,shmop,sockets,sysvmsg,sysvsem,sysvshm,tokenizer}
```
php8.3-cli installs the PHP CLI, and symlinks /usr/bin/php to /usr/bin/php8.3. See Running PHP 8.3 Alongside Other Versions for more information.
php8.3-fpm installs PHP's FPM SAPI for web server integration. See Web Server Integration for alternative approaches.

5. Additional PHP Extensions

Several PECL extensions are also available in the repository to conveniently install them without having to compile them. This includes some of the more popular PECL extensions such as Image Magick, APCu, and Xdebug.

The following are some of the PECL extensions and their package names to be used with apt install to install.

Extension name	Package name
Xdebug	`php8.3-xdebug`
Redis	`php8.3-redis`
PCov	`php8.3-pcov`
Image Magick	`php8.3-imagick`
APCu	`php8.3-apcu`

Note that these PECL extensions are developed by individual developers/teams, and may not be as well tested. It might also take some for these packages to be uploaded, pending compatibility fixes from corresponding extension developments.

The following runs a simple search on apt:

sudo apt search php8.3-apcu # Search for "apcu" under PHP 8.3

The packages.txt file created in step #2 should come handy here, to refer to the existing PHP packages.

6. Web Server Integration

In most of the use cases, PHP is integrated with a web server. Integrating with PHP-FPM over Fast CGI protocol is the most common approach, while it is also possible to integrate PHP with other SAPIs.

Apache web server
When installing php8.3-fpm package, if Apache web server (apache2) is present, there will be a new php8.3-fpm.conf file that makes it convenient to toggle PHP 8.3 integration:

sudo a2enconf php8.3-fpm
sudo a2disconf php8.2-fpm # When upgrading from an older PHP version
sudo systemctl restart apache2

When Apache is configured to run PHP as an Apache module (commonly called as mod_php or mod_php8), install libapache2-mod-php8.3 package instead of php8.3-fpm:

sudo apt install libapache2-mod-php8.3
sudo a2enmod php8.3
sudo a2dismod php8.2 # When upgrading from an older PHP version
sudo systemctl restart apache2

Nginx, Caddy, Litespeed, and other servers over Fast CGI

The php8.3-fpm installs PHP-FPM, and registers a systemd service for PHP 8.3 FPM at socket address /run/php/php8.3-fpm.sock.

For web servers that integrate with PHP over Fast CGI, change/configure the UNIX socket path to this UNIX socket address.

For example, on Nginx, this involves changing the fastcgi_pass directive:

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

See How to use Caddy Server with PHP for a detailed article on using Caddy server with PHP.

7. Test PHP 8.3 Installation

After installing all the packages, comes the moment of truth to see if the new installation was successful.

Running php -v in the terminal should show something like this:

php -v output — Calling `php -v` displays the PHP version number and build date.

The list of modules can be listed with php -m. This list will include several bundled PHP extensions. See Migrate Configuration on migrating the PHP INI directives and enabled extensions to the new PHP versions.

8. Migrate Configuration

This step only applies when updating to PHP 8.3 from an older PHP version

Configuration files for the new PHP 8.3 installation are at /etc/php/8.3 directory. Existing PHP installations should also be in the /etc/php directory.

Do not copy existing PHP INI files to /etc/php/8.3. Instead, compare two corresponding PHP INI files and update the PHP 8.3 variant only when necessary.

See What's new and changed in PHP 8.3 to see the deprecated INI directives and the new INI directive added in PHP 8.3.

When using PHP-FPM, make sure to replicate the correct number of FPM processes and process models.

phpenmod and phpdismod scripts provide continent toggles for PHP modules. For example, the following disables the phar extension for FPM on PHP 8.3:

sudo phpdismod -v 8.3 -s fpm phar

After making changes, restart PHP 8.3-FPM:

sudo systemctl restart php8.3-fpm

9. Remove old PHP Versions

This step only applies when updating to PHP 8.3 from an older PHP version

To remove old PHP versions, run apt purge with the PHP version prefix. For example, the following removes the packages and configuration for PHP 8.2:

sudo apt purge php8.2*

Running PHP 8.3 Alongside Other Versions

It is possible to install PHP 8.3 alongside other PHP versions. This is in fact what happens when installing PHP 8.3 without removing old PHP packages first.

By default, all phpX.Y-cli packages install PHP CLI binary at /usr/bin/phpX.Y location. What this means for PHP 8.3 installations is that the any application that calls PHP CLI as php will use the last-installed PHP-CLI binary (PHP 8.3 in this case). When using multiple PHP versions, make sure to invoke the correct PHP binary by directly calling the /usr/bin/phpX.Y executable. PHP 8.3 can be directly invoked as /usr/bin/php8.3.

The default php name will be symlinked to the latest PHP version by default, but it is possible to change to where the default php command links. Use update-alternatives command to change the path to which php command should be linked.

sudo update-alternatives --config php

This brings up a prompt to interactively select the alternative PHP binary path that php points to.

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

  Selection    Path             Priority   Status
------------------------------------------------------------
* 0            /usr/bin/php8.3   83        auto mode
  1            /usr/bin/php8.2   82        manual mode
  2            /usr/bin/php8.3   83        manual mode

To set the path without the interactive prompt:

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