Installation (Linux)#

Applies to Linux and Windows

2024-01-19

14 min read time

Warning

ROCm currently doesn’t support integrated graphics. Should your system have an AMD IGP installed, disable it in the BIOS prior to using ROCm. If the driver can enumerate the IGP, the ROCm runtime may crash the system, even if told to omit it via HIP_VISIBLE_DEVICES.

Understanding the Release-specific AMDGPU and ROCm Repositories on Linux Distributions#

The release-specific repositories consist of packages from a specific release of versions of AMDGPU and ROCm. The repositories are not updated for the latest packages with subsequent releases. When a new ROCm release is available, the new repository, specific to that release, is added. You can select a specific release to install, update the previously installed single version to the later available release, or add the latest version of ROCm along with the currently installed version by using the multi-version ROCm packages.

Step by Step Instructions#

1. Download and convert the package signing key

# Make the directory if it doesn't exist yet.
# This location is recommended by the distribution maintainers.
sudo mkdir --parents --mode=0755 /etc/apt/keyrings
# Download the key, convert the signing-key to a full
# keyring required by apt and store in the keyring directory
wget https://repo.radeon.com/rocm/rocm.gpg.key -O - | \
    gpg --dearmor | sudo tee /etc/apt/keyrings/rocm.gpg > /dev/null

Note

The GPG key may change; ensure it is updated when installing a new release. If the key signature verification fails while updating, re-add the key from the ROCm to the apt repository as mentioned above. The current rocm.gpg.key is not available in a standard key ring distribution but has the following SHA1 sum hash: 73f5d8100de6048aa38a8b84cd9a87f05177d208 rocm.gpg.key

2. Add the AMDGPU Repository and Install the Kernel-mode Driver

Tip

If you have a version of the kernel-mode driver installed, you may skip this section.

To add the AMDGPU repository, follow these steps:

# version
ver=5.7

# amdgpu repository for focal
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/amdgpu/$ver/ubuntu focal main" \
    | sudo tee /etc/apt/sources.list.d/amdgpu.list
sudo apt update
# version
ver=5.7

# amdgpu repository for jammy
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/amdgpu/$ver/ubuntu jammy main" \
    | sudo tee /etc/apt/sources.list.d/amdgpu.list
sudo apt update
# Prefer packages from the rocm repository over system packages
echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' | sudo tee /etc/apt/preferences.d/rocm-pin-600

Install the kernel mode driver and reboot the system using the following commands:

sudo apt install amdgpu-dkms
sudo reboot

3. Add the ROCm Repository

To add the ROCm repository, use the following steps:

# ROCm repositories for focal
for ver in 5.3.3 5.4.6 5.5.3 5.6.1 5.7; do
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/rocm/apt/$ver focal main" \
    | sudo tee --append /etc/apt/sources.list.d/rocm.list
done
echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' \
    | sudo tee /etc/apt/preferences.d/rocm-pin-600
sudo apt update
# ROCm repositories for jammy
for ver in 5.3.3 5.4.6 5.5.3 5.6.1 5.7; do
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/rocm/apt/$ver jammy main" \
    | sudo tee --append /etc/apt/sources.list.d/rocm.list
done
echo -e 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600' \
    | sudo tee /etc/apt/preferences.d/rocm-pin-600
sudo apt update

4. Install packages

Install packages of your choice in a single-version ROCm install or in a multi-version ROCm install fashion. For more information on what single/multi-version installations are, refer to Single Version ROCm install versus Multi-Version. For a comprehensive list of meta-packages, refer to Meta-packages and Their Descriptions.

  • Sample Single-version installation

    sudo apt install rocm-hip-sdk
    
  • Sample Multi-version installation

    sudo apt install rocm-hip-sdk5.7 rocm-hip-sdk5.6.1 rocm-hip-sdk5.5.3
    

1. Add the AMDGPU Stack Repository and Install the Kernel-mode Driver

Tip

If you have a version of the kernel-mode driver installed, you may skip this section.

# version
ver=5.7

sudo tee /etc/yum.repos.d/amdgpu.repo <<EOF
[amdgpu]
name=amdgpu
baseurl=https://repo.radeon.com/amdgpu/$ver/rhel/8.7/main/x86_64/
enabled=1
priority=50
gpgcheck=1
gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
EOF
sudo yum clean all
# version
ver=5.7

sudo tee /etc/yum.repos.d/amdgpu.repo <<EOF
[amdgpu]
name=amdgpu
baseurl=https://repo.radeon.com/amdgpu/$ver/rhel/8.8/main/x86_64/
enabled=1
priority=50
gpgcheck=1
gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
EOF
sudo yum clean all
# version
ver=5.7

sudo tee /etc/yum.repos.d/amdgpu.repo <<EOF
[amdgpu]
name=amdgpu
baseurl=https://repo.radeon.com/amdgpu/$ver/rhel/9.1/main/x86_64/
enabled=1
priority=50
gpgcheck=1
gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
EOF
sudo yum clean all
# version
ver=5.7

sudo tee /etc/yum.repos.d/amdgpu.repo <<EOF
[amdgpu]
name=amdgpu
baseurl=https://repo.radeon.com/amdgpu/$ver/rhel/9.2/main/x86_64/
enabled=1
priority=50
gpgcheck=1
gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
EOF
sudo yum clean all

Install the kernel mode driver and reboot the system using the following commands:

sudo yum install amdgpu-dkms
sudo reboot

2. Add the ROCm Stack Repository

To add the ROCm repository, use the following steps, based on your distribution:

for ver in 5.3.3 5.4.6 5.5.3 5.6.1 5.7; do
sudo tee --append /etc/yum.repos.d/rocm.repo <<EOF
[ROCm-$ver]
name=ROCm$ver
baseurl=https://repo.radeon.com/rocm/rhel8/$ver/main
enabled=1
priority=50
gpgcheck=1
gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
EOF
done
sudo yum clean all
for ver in 5.3.3 5.4.6 5.5.3 5.6.1 5.7; do
sudo tee --append /etc/yum.repos.d/rocm.repo <<EOF
[ROCm-$ver]
name=ROCm$ver
baseurl=https://repo.radeon.com/rocm/rhel9/$ver/main
enabled=1
priority=50
gpgcheck=1
gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
EOF
done
sudo yum clean all

3. Install packages

Install packages of your choice in a single-version ROCm install or in a multi-version ROCm install fashion. For more information on what single/multi-version installations are, refer to Single Version ROCm install versus Multi-Version. For a comprehensive list of meta-packages, refer to Meta-packages and Their Descriptions.

  • Sample Single-version installation

    sudo yum install rocm-hip-sdk
    
  • Sample Multi-version installation

    sudo yum install rocm-hip-sdk5.7 rocm-hip-sdk5.6.1
    

1. Add the AMDGPU Repository and Install the Kernel-mode Driver

Tip

If you have a version of the kernel-mode driver installed, you may skip this section.

# version
ver=5.7


sudo tee /etc/zypp/repos.d/amdgpu.repo <<EOF
[amdgpu]
name=amdgpu
baseurl=https://repo.radeon.com/amdgpu/$ver/sle/15.4/main/x86_64
enabled=1
gpgcheck=1
gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
EOF
sudo zypper ref
# version
ver=5.7

sudo tee /etc/zypp/repos.d/amdgpu.repo <<EOF
[amdgpu]
name=amdgpu
baseurl=https://repo.radeon.com/amdgpu/$ver/sle/15.5/main/x86_64
enabled=1
gpgcheck=1
gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
EOF
sudo zypper ref

Install the kernel mode driver and reboot the system using the following commands:

sudo zypper --gpg-auto-import-keys install amdgpu-dkms
sudo reboot

2. Add the ROCm Stack Repository

To add the ROCm repository, use the following steps:

for ver in 5.3.3 5.4.6 5.5.3 5.6.1 5.7; do
sudo tee --append /etc/zypp/repos.d/rocm.repo <<EOF
[ROCm-$ver]
name=ROCm$ver
name=rocm
baseurl=https://repo.radeon.com/rocm/zyp/$ver/main
enabled=1
gpgcheck=1
gpgkey=https://repo.radeon.com/rocm/rocm.gpg.key
EOF
done
sudo zypper ref

3. Install packages

Install packages of your choice in a single-version ROCm install or in a multi-version ROCm install fashion. For more information on what single/multi-version installations are, refer to Single Version ROCm install versus Multi-Version. For a comprehensive list of meta-packages, refer to Meta-packages and Their Descriptions.

  • Sample Single-version installation

    sudo zypper --gpg-auto-import-keys install rocm-hip-sdk
    
  • Sample Multi-version installation

    sudo zypper --gpg-auto-import-keys install rocm-hip-sdk5.7 rocm-hip-sdk5.6.1
    

Post-install Actions and Verification Process#

The post-install actions listed here are optional and depend on your use case, but are generally useful. Verification of the install is advised.

Post-install Actions#

  1. Instruct the system linker where to find the shared objects (.so files) for ROCm applications.

    sudo tee --append /etc/ld.so.conf.d/rocm.conf <<EOF
    /opt/rocm/lib
    /opt/rocm/lib64
    EOF
    sudo ldconfig
    

    Note

    Multi-version installations require extra care. Having multiple versions on the system linker library search path is unadvised. One must take care both at compile-time and at run-time to assure that the proper libraries are picked up. You can override ld.so.conf entries on a case-by-case basis using the LD_LIBRARY_PATH environmental variable.

  2. Add binary paths to the PATH environment variable.

    export PATH=$PATH:/opt/rocm-5.7/bin:/opt/rocm-5.7/opencl/bin
    

    Attention

    When using CMake to build applications, having the ROCm install location on the PATH subtly affects how ROCm libraries are searched for. See Config Mode Search Procedure and CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH for details.

    (Entries in the PATH minus bin and sbin are added to library search paths, therefore this convenience will affect builds and result in ROCm libraries almost always being found. This may be an issue when you’re developing these libraries or want to use self-built versions of them.)

Verifying Kernel-mode Driver Installation#

Check the installation of the kernel-mode driver by typing the command given below:

dkms status

Verifying ROCm Installation#

After completing the ROCm installation, execute the following commands on the system to verify if the installation is successful. If you see your GPUs listed by both commands, the installation is considered successful:

/opt/rocm/bin/rocminfo
# OR
/opt/rocm/opencl/bin/clinfo

Verifying Package Installation#

To ensure the packages are installed successfully, use the following commands:

sudo apt list --installed
sudo yum list installed
sudo zypper search --installed-only