How to install or upgrade to PHP 8.3 on Ubuntu and Debian
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
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.txt3. 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 updateUbuntu
sudo add-apt-repository ppa:ondrej/php # Press enter when prompted.
sudo apt update4. 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-commonpackage 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. Installingphp8.3-commonis 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-cliinstalls the PHP CLI, and symlinks/usr/bin/phpto/usr/bin/php8.3. See Running PHP 8.3 Alongside Other Versions for more information. -
php8.3-fpminstalls 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.3The 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 apache2When 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 apache2Nginx, 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:
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-fpm9. 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 phpThis 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 modeTo set the path without the interactive prompt:
update-alternatives --set php /usr/bin/php8.2
