Manage multiple PHP versions on Ubuntu with PHP-FPM

Install several PHP-FPM versions on one Ubuntu server, set the CLI default, and point each Nginx site at the PHP version it needs.

  • Intermediate
  • Linux VPS
  • 6 min read

By RunRacks Team · Published

You can run multiple PHP versions on Ubuntu at the same time by installing each version as its own PHP-FPM service and pointing each Nginx site at that version's FPM socket. This guide installs two PHP versions, sets the command-line default, and configures two sites to use different runtimes.

This is useful when one application needs a newer PHP release while a legacy site still depends on an older branch. Each PHP version runs as a separate service, so upgrading one site does not force an upgrade on the other.

Before you start

You need:

The examples install PHP 8.2 and PHP 8.3. Adjust the version numbers to the branches your applications support. PHP release support changes over time, so check the PHP project's supported versions page before choosing a branch.

Install multiple PHP versions with PHP-FPM

Add the PHP package repository, then install both PHP-FPM services and the extensions your sites need.

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

Install PHP 8.2 and PHP 8.3 with FPM, CLI and common extensions:

Terminal
sudo apt install -y \
  php8.2-fpm php8.2-cli php8.2-mysql php8.2-curl php8.2-mbstring php8.2-xml php8.2-zip \
  php8.3-fpm php8.3-cli php8.3-mysql php8.3-curl php8.3-mbstring php8.3-xml php8.3-zip

Enable and start both FPM services:

Terminal
sudo systemctl enable --now php8.2-fpm php8.3-fpm

Check that each service is active:

Terminal
systemctl status php8.2-fpm --no-pager
systemctl status php8.3-fpm --no-pager

List the FPM sockets:

Terminal
ls -l /run/php/

You should see sockets such as php8.2-fpm.sock and php8.3-fpm.sock. Nginx connects to these Unix sockets. If a socket is missing, the matching FPM service is not running or its pool configuration failed to load.

Set the command-line PHP default to the version you want for SSH work:

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

The php -v output should show PHP 8.3. This changes only the CLI default. It does not change which PHP version Nginx uses for a website.

Point each Nginx site at a PHP version

Each Nginx server block chooses a PHP version by using a different fastcgi_pass socket. Create a site that uses PHP 8.3:

Terminal
sudo mkdir -p /var/www/example.com/public
echo '<?php echo PHP_VERSION;' | sudo tee /var/www/example.com/public/version.php
sudo chown -R www-data:www-data /var/www/example.com

Create /etc/nginx/sites-available/example.com:

NGINX
server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/example.com/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
}

Create a second site that uses PHP 8.2:

Terminal
sudo mkdir -p /var/www/legacy.example.com/public
echo '<?php echo PHP_VERSION;' | sudo tee /var/www/legacy.example.com/public/version.php
sudo chown -R www-data:www-data /var/www/legacy.example.com

Create /etc/nginx/sites-available/legacy.example.com:

NGINX
server {
    listen 80;
    server_name legacy.example.com;

    root /var/www/legacy.example.com/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

Enable both sites and test the Nginx configuration:

Terminal
sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com
sudo ln -s /etc/nginx/sites-available/legacy.example.com /etc/nginx/sites-enabled/legacy.example.com
sudo nginx -t
sudo systemctl reload nginx

If nginx -t reports a duplicate default server or a missing file, fix that before reloading. A reload is safer than a restart because it keeps existing connections open.

Check it works

Request the test file from each hostname. If DNS is not live yet, send the Host header to the server IP:

Terminal
curl -sS -H 'Host: example.com' http://203.0.113.10/version.php
curl -sS -H 'Host: legacy.example.com' http://203.0.113.10/version.php

The first response should show an 8.3 version string and the second should show an 8.2 version string. You can also check the active FPM sockets:

Terminal
ss -xl | grep php

For a quick service check:

Terminal
systemctl is-active php8.2-fpm php8.3-fpm

Both services should return active. If one site returns the wrong PHP version, inspect its Nginx server block and confirm the fastcgi_pass line points to the intended socket.

Troubleshooting

  • 502 Bad Gateway after reloading Nginx → Nginx cannot reach the FPM socket. Check ls -l /run/php/, confirm the service is running with systemctl status php8.3-fpm, and compare the socket path in the site config. Read /var/log/nginx/error.log for the exact connect error.
  • “File not found” or “Primary script unknown” → The Nginx root path or the PHP script path is wrong. Confirm the file exists under the configured root and that the location ~ \.php$ block includes snippets/fastcgi-php.conf.
  • The site still uses the old PHP version → The server block still points at the old socket, or another matching server block is being used. Run grep -R "fastcgi_pass" /etc/nginx/sites-enabled/ and reload Nginx after fixing the file.
  • Permission denied connecting to the socket → The FPM pool user or socket permissions do not match the Nginx worker user. On Ubuntu, Nginx usually runs as www-data; check the pool file under /etc/php/8.3/fpm/pool.d/www.conf and the socket owner with ls -l /run/php/php8.3-fpm.sock.
  • APT cannot find `php8.3-fpm` → The PHP repository is missing or does not support your Ubuntu release. Run apt-cache policy php8.3-fpm, confirm the repository was added, and check the vendor's documentation for supported releases.

Next steps

Was this guide helpful?

Still stuck?

Ask RunRacks AI for a quick answer, or open a ticket and our team will take a look at your server.

Control panels

CyberPanel: back up and restore a website

Create on-demand and scheduled website backups in CyberPanel, download the archives off the server, and restore a site from a backup when something breaks.

  • Intermediate
  • Linux VPS
  • 6 min read