When managing a server, it's crucial to maintain a specific version of a package to ensure smooth functioning. By default, Debian updates packages to the latest available versions, which may cause unexpected issues. In this guide, we'll go through the steps to stick to PHP 8.1 on Debian 12 and prevent unintended upgrades as an example.
Step 1: Check Your Current PHP Version
Before applying any restrictions, verify your installed PHP version:
php -v
This should display output similar to:
PHP 8.1.32 (cli) (built: Mar 13 2025 12:00:00) ( NTS )
Copyright (c) The PHP Group
Ensure you are running PHP 8.1 before proceeding.
Step 2: Hold PHP 8.1 Packages
The apt-mark command prevents APT from upgrading certain packages:
sudo apt-mark hold php8.1 php8.1-cli php8.1-common php8.1-curl php8.1-gd php8.1-intl php8.1-mbstring php8.1-mysql php8.1-opcache php8.1-readline php8.1-soap php8.1-xml php8.1-xmlrpc php8.1-zip libapache2-mod-php8.1 php-common
To verify that PHP packages are held, run:
apt-mark showhold
If successful, you should see all PHP 8.1-related packages listed.
Step 3: Pin PHP 8.1 Using APT Preferences
To further enforce PHP 8.1, create a pinning rule in /etc/apt/preferences.d/php:
sudo nano /etc/apt/preferences.d/php
Add the following lines:
Package: php*
Pin: version 8.1*
Pin-Priority: 1001
Save and exit (CTRL+X, then Y, then ENTER).
This ensures that only PHP 8.1.x versions are installed and prevents Debian from upgrading PHP to newer versions (like 8.2 or 8.3).
To check if the pin is correctly applied, run:
apt-cache policy php8.1
You should see:
Installed: 8.1.32-1
Candidate: 8.1.32-1
Pin-Priority: 1001
This confirms that PHP 8.1 is locked at priority 1001, preventing unwanted upgrades.
Step 4: Verify Everything Works
To ensure PHP 8.1 remains active and isn’t upgradable:
php -v
apt-mark showhold
apt-cache policy php8.1
sudo apt update && apt list --upgradable | grep php
If PHP doesn't appear in the upgradable list, you're successfully locked on PHP 8.1!
Step 5: If You Ever Want to Upgrade PHP
If in the future you want to upgrade PHP, remove the hold and pinning:
sudo apt-mark unhold php8.1 php8.1-cli php8.1-common php8.1-curl php8.1-gd php8.1-intl php8.1-mbstring php8.1-mysql php8.1-opcache php8.1-readline php8.1-soap php8.1-xml php8.1-xmlrpc php8.1-zip libapache2-mod-php8.1 php-common
sudo rm /etc/apt/preferences.d/php
sudo apt update && sudo apt upgrade
This will allow PHP to be updated to the latest version available.
