Migrate to AlmaLinux

This guide walks you through using the official AlmaLinux migration tool almalinux-deploy to migrate from CentOS 7/8, CentOS Stream, RHEL, or other EL-compatible distributions to AlmaLinux.

Prerequisites

Before starting the migration, confirm the following:

Operating system version: CentOS 7, CentOS 8, CentOS Stream 8/9, RHEL 7/8/9, Oracle Linux, Rocky Linux, or other EL-compatible systems
Disk space: At least 5 GB of free space on the /var partition (for downloading and caching packages)
Network connectivity: The server must be able to access the internet to download AlmaLinux packages
Root privileges: The migration process requires root or sudo privileges
Full backup: Be sure to create a system snapshot or full backup before migrating

Important: The migration process replaces core system packages and carries some risk. Always validate in a test environment before running it in production.

Record the Current System State

$ cat /etc/os-release

$ rpm -qa --queryformat '%{NAME}-%{VERSION}-%{RELEASE}.%{ARCH}\n' | sort > ~/packages-before-migration.txt

$ systemctl list-units --type=service --state=running > ~/services-before-migration.txt

$ cp -a /etc/yum.repos.d/ ~/yum.repos.d.bak/

$ nmcli connection show > ~/network-before-migration.txt
$ ip addr show > ~/ip-addr-before-migration.txt

Download the almalinux-deploy Tool

almalinux-deploy is the official migration script provided by AlmaLinux, hosted on GitHub.

$ sudo dnf install -y curl

$ curl -O https://raw.githubusercontent.com/AlmaLinux/almalinux-deploy/master/almalinux-deploy.sh

$ ls -la almalinux-deploy.sh

Tip: If your server cannot access GitHub directly, you can download the script on another machine and transfer it to the target server via scp.

Perform the Migration

Basic Migration (CentOS 8 / CentOS Stream)

$ sudo bash almalinux-deploy.sh

The script automatically performs the following steps:

Detects the current operating system version
Downloads AlmaLinux GPG keys and repository configuration
Removes CentOS-specific packages (such as centos-release, centos-logos, etc.)
Installs the corresponding AlmaLinux packages
Runs dnf distro-sync to synchronize all packages to AlmaLinux versions

Migrating from CentOS 7

CentOS 7 migration requires upgrading to EL8 first, since almalinux-deploy primarily supports direct migration for EL8+. AlmaLinux provides the ELevate project to handle cross-major-version upgrades.

$ sudo yum install -y http://repo.almalinux.org/elevate/elevate-release-latest-el7.noarch.rpm

$ sudo yum install -y leapp-upgrade leapp-data-almalinux

$ sudo leapp preupgrade

Note: leapp preupgrade generates a report listing all issues that require manual resolution. Carefully review /var/log/leapp/leapp-report.txt and address each one.

$ sudo cat /var/log/leapp/leapp-report.txt

$ sudo leapp upgrade

After the upgrade completes, the system will automatically reboot into AlmaLinux 8.

No Target-Version Option

almalinux-deploy.sh has no option to pick a target version: -t is --tests (run the checks only, no conversion) and exits immediately; the resulting version is determined by the source major version (EL8 -> AlmaLinux 8, EL9 -> AlmaLinux 9).

$ sudo bash almalinux-deploy.sh -t
# When the output looks right, run the conversion without -t
$ sudo bash almalinux-deploy.sh

Cross-major moves (e.g. EL8 -> EL9) are not this script’s job: almalinux-deploy handles same-major conversion; see EL 8 to EL 9.

Handling Third-Party Repositories

Third-party repositories may cause package conflicts during migration. Below are common approaches.

EPEL Repository

The EPEL repository usually adapts automatically, but it is recommended to temporarily disable it before migration:

$ sudo dnf config-manager --set-disabled epel epel-modular 2>/dev/null

$ sudo dnf install -y epel-release
$ sudo dnf config-manager --set-enabled epel

Remi / IUS / RPMFusion and Other Repositories

$ dnf repolist --enabled | grep -v -E '^(baseos|appstream|extras|powertools|crb)'

$ sudo dnf config-manager --set-disabled remi* ius* rpmfusion*

After migration, reinstall the third-party repository versions compatible with AlmaLinux:

$ sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm

$ sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-9.rpm

Resolving Package Conflicts

If package conflicts occur during migration:

$ rpm -qa --qf '%{NAME} %{VENDOR}\n' | grep -v "AlmaLinux" | sort

$ sudo dnf distro-sync -y

Post-Migration Verification

Confirm the OS Has Been Switched

$ cat /etc/os-release

The output should show AlmaLinux information:

NAME="AlmaLinux"
VERSION="8.9 (Midnight Oncilla)"
ID="almalinux"

$ rpm -qa | grep almalinux-release

Verify Package Integrity

$ rpm -qa | grep -i centos

If there are leftover packages, you can manually remove or replace them:

$ sudo dnf remove centos-logos centos-indexhtml 2>/dev/null
$ sudo dnf distro-sync -y

Rebuild GRUB Boot Configuration

$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg

For EFI systems:

$ sudo grub2-mkconfig -o /boot/efi/EFI/almalinux/grub.cfg

Reboot and Verify

$ sudo reboot

$ uname -r

$ systemctl list-units --type=service --state=failed

Common Issues

Migration script reports “not supported”

Confirm that your source system version is in the supported list. CentOS 6 and earlier versions are not supported.

$ cat /etc/redhat-release

GPG key import failure

This may be caused by network issues preventing the key from being downloaded.

$ sudo rpm --import https://repo.almalinux.org/almalinux/RPM-GPG-KEY-AlmaLinux-8

dnf distro-sync failure

This is usually caused by third-party repository package conflicts.

$ sudo dnf distro-sync -y --exclude=<conflicting-package-name>

$ sudo dnf clean all
$ sudo dnf distro-sync -y

Unable to boot after migration

If the system enters GRUB rescue or fails to boot after restarting:

Boot using installation media or rescue mode
Mount the root partition
chroot into the system
Reinstall the kernel and GRUB

$ sudo mount /dev/sda2 /mnt
$ sudo mount /dev/sda1 /mnt/boot
$ sudo chroot /mnt
$ dnf reinstall kernel-core grub2-efi-x64 shim-x64
$ grub2-mkconfig -o /boot/efi/EFI/almalinux/grub.cfg
$ exit
$ sudo reboot