Migrate to Rocky Linux

This guide walks you through using the official Rocky Linux migration tool migrate2rocky.sh to migrate from CentOS 8, CentOS Stream, RHEL, AlmaLinux, Oracle Linux, and other EL-compatible distributions to Rocky Linux.

Prerequisites

Before starting the migration, confirm the following:

• Operating system version: CentOS 8, CentOS Stream 8/9, RHEL 8/9, AlmaLinux 8/9, Oracle Linux 8/9, or other EL8+ compatible systems
• Disk space: At least 5 GB of free space on the /var partition
• Network connectivity: The server must be able to access the internet to download Rocky Linux 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: migrate2rocky.sh currently supports EL8 and EL9 systems only. CentOS 7 users need to upgrade to EL8 first before using this tool.

Record the Current System State

Confirm the current OS version

$ cat /etc/os-release

Back up the list of installed packages

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

Back up running services

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

Back up repository configuration

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

Create a system snapshot (if using LVM)

$ sudo lvcreate --size 10G --snapshot --name pre_migration_snap /dev/mapper/centos-root

Download the migrate2rocky.sh Tool

migrate2rocky.sh is officially maintained by Rocky Linux and hosted on GitHub.

Install required tools

$ sudo dnf install -y curl git

There are two ways to obtain the migration script:

Option 1: Download the Script Directly

Download migrate2rocky.sh

$ curl -O https://raw.githubusercontent.com/rocky-linux/rocky-tools/main/migrate2rocky/migrate2rocky.sh

Option 2: Clone the Entire Repository

Clone the rocky-tools repository

$ git clone https://github.com/rocky-linux/rocky-tools.git
$ cd rocky-tools/migrate2rocky/

Confirm the script is ready

$ ls -la migrate2rocky.sh

Perform the Migration

Basic Migration (CentOS 8 / CentOS Stream 8)

Run the migration script

$ sudo bash migrate2rocky.sh -r

The -r flag performs a full migration (including dnf distro-sync). The script automatically completes the following steps:

1. Detects the current operating system and version
2. Checks for known incompatibilities
3. Downloads Rocky Linux GPG keys
4. Replaces system identifier packages (*-release, *-logos, *-gpg-keys, etc.)
5. Runs dnf distro-sync to synchronize all packages to Rocky Linux versions

Migrating EL9 Systems

For CentOS Stream 9, AlmaLinux 9, and other EL9 systems:

Download the EL9 version of the migration script

$ curl -O https://raw.githubusercontent.com/rocky-linux/rocky-tools/main/migrate2rocky/migrate2rocky9.sh

Run the EL9 migration

$ sudo bash migrate2rocky9.sh -r

Migration Path for CentOS 7

CentOS 7 cannot be directly migrated to Rocky Linux. You need to use the ELevate project to upgrade to EL8 first.

Install the ELevate repository (CentOS 7)

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

Install the Leapp upgrade tool (targeting Rocky Linux 8)

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

Run the pre-upgrade check

$ sudo leapp preupgrade

Review the report and resolve all issues

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

Proceed with the upgrade after resolving all issues

$ sudo leapp upgrade

After reboot, the system will boot directly into Rocky Linux 8.

Handling Third-Party Repositories

Third-party repositories are the most common source of issues during migration. It is recommended to handle them properly before migrating.

Disable Third-Party Repositories Before Migration

List all enabled repositories

$ dnf repolist --enabled

Disable EPEL repository

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

Disable other common third-party repositories

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

Restore Third-Party Repositories After Migration

After migration, install the third-party repository packages for the corresponding Rocky Linux version:

Install EPEL (Rocky Linux 8)

$ sudo dnf install -y epel-release

Install EPEL (Rocky Linux 9)

$ sudo dnf install -y epel-release

Install ELRepo (for newer kernels, etc.)

$ sudo dnf install -y https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm

Install Remi (Rocky Linux 8)

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

Install Remi (Rocky Linux 9)

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

Handling Katello / Satellite Managed Systems

If the system is managed by Katello or Red Hat Satellite:

Unregister before migration

$ sudo subscription-manager unregister
$ sudo subscription-manager clean

Reconfigure management tools as needed after migration.

Post-Migration Verification

Confirm the System Version

Verify the system version

$ cat /etc/os-release

Expected output:

NAME="Rocky Linux"
VERSION="8.9 (Green Obsidian)"
ID="rocky"

Verify the distribution identifier package

$ rpm -qa | grep rocky-release

Check for Leftover Packages

Find non-Rocky Linux leftover packages

$ rpm -qa --qf '%{NAME} %{VENDOR}\n' | grep -v -i rocky | grep -v "(none)" | sort

Check for leftover CentOS packages

$ rpm -qa | grep -i centos

Remove leftover packages (if any)

$ sudo dnf remove centos-logos centos-indexhtml centos-backgrounds 2>/dev/null

Synchronize All Packages

Ensure all packages are synced to Rocky Linux versions

$ sudo dnf distro-sync -y

Rebuild GRUB Boot Configuration

Rebuild GRUB for BIOS systems

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

Rebuild GRUB for EFI systems

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

Reboot and Final Verification

Reboot the system

$ sudo reboot

Check the kernel version after reboot

$ uname -r

Check for failed services

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

Compare package lists before and after migration

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

Common Issues

Script reports “Unsupported OS”

migrate2rocky.sh only supports EL8 systems. If you are running CentOS 7, you need to use the ELevate project to upgrade to EL8 first. For EL9, use migrate2rocky9.sh.

Confirm your EL major version

$ rpm -E %{rhel}

Error: “Could not download Rocky Linux GPG keys”

Network issues preventing GPG key download.

Test connectivity to Rocky Linux mirrors

$ curl -I https://dl.rockylinux.org/

Manually import GPG keys

$ sudo rpm --import https://dl.rockylinux.org/pub/rocky/RPM-GPG-KEY-Rocky-8

If the server is in China, consider using a mirror for faster access.

dnf distro-sync reports package conflicts

View conflict details

$ sudo dnf distro-sync -y --allowerasing 2>&1 | tee /tmp/distro-sync.log

Exclude specific problematic packages and retry

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

If multi-version conflicts exist, clear and rebuild the cache

$ sudo dnf clean all
$ sudo rm -rf /var/cache/dnf
$ sudo dnf makecache
$ sudo dnf distro-sync -y

SSH connection drops after migration

If SSH disconnects during migration, reconnect through the console (IPMI / KVM / cloud platform console).

Recommendation: Run the migration script inside a screen or tmux session to prevent network interruptions from terminating the migration process.

Run migration in tmux

$ tmux new -s migration
$ sudo bash migrate2rocky.sh -r

If the tmux session disconnects, reattach:

Reattach the tmux session

$ tmux attach -t migration

System fails to boot after migration

Refer to the Boot Issues Troubleshooting page. Typically, the kernel and GRUB need to be reinstalled from rescue mode.

Next Steps

• Post-Migration Checklist — Complete post-migration verification steps
• Migration Overview — Compare migration options