Run On AMD GPUs On Linux: A Comprehensive Guide

Dec 4, 2025 by Alex Johnson 48 views

Running on AMD GPUs on Linux: A Comprehensive Guide

Are you looking to harness the power of your AMD GPU on a Linux system? This guide provides a detailed walkthrough, specifically tested with an RX 7900 under Fedora 43, utilizing Distrobox for a streamlined runtime environment. This ensures compatibility and optimal performance for your applications. This guide will walk you through the process step-by-step, ensuring you can leverage your AMD GPU's capabilities on Linux.

Addressing Wayland Issues

Before diving into the setup, it's crucial to address a known issue with Wayland and window sizing. If you encounter problems with window dimensions, you may need to modify the modules/ui.py file. This section provides a safety patch to ensure proper image display, especially when the window hasn't fully rendered yet. This is a crucial step for a smooth user experience.

def fit_image_to_size(image, width: int, height: int):
    if width is None and height is None:
        return image
    h, w, _ = image.shape

    # SAFETY PATCH: If the window hasn't drawn yet, return the original image
    if width < 1 or height < 1:
        return image

    ratio_h = 0.0
    ratio_w = 0.0
    if width > height:
        ratio_h = height / h
    else:
        ratio_w = width / w
    ratio = max(ratio_w, ratio_h)
    new_size = (int(ratio * w), int(ratio * h))

    # SAFETY PATCH: If calculated size is zero, return original
    if new_size[0] < 1 or new_size[1] < 1:
        return image

    return cv2.resize(image, dsize=new_size)

This code snippet acts as a crucial safeguard, preventing errors and ensuring your application functions correctly within the Wayland environment. The safety patches prevent the application from crashing when the window size is not yet determined or if the calculated size is zero. This ensures that the original image is returned, preventing any display issues.

Step-by-Step Guide to Running on AMD GPUs on Linux

Here's a comprehensive, step-by-step guide to get your application running smoothly on your AMD GPU within a Linux environment. This process involves setting up a containerized environment using Distrobox, installing necessary dependencies, and configuring the application to utilize the ROCm execution provider. Each step is detailed below to ensure a successful setup.

1. Leveraging Distrobox for a Clean Environment

We highly recommend using Distrobox to create a containerized environment. Distrobox offers a clean and isolated space, preventing conflicts with your host system's libraries and dependencies. This approach ensures that your application has the specific environment it needs to function optimally. It’s like having a dedicated sandbox for your application, minimizing potential issues. Think of it as creating a virtual environment tailored specifically for your application's needs, ensuring consistency and reproducibility.

2. Creating a Distrobox Container with ROCm

Create a new Distrobox container based on the rocm/onnxruntime:rocm7.0_ub24.04_ort1.22_torch2.8.0 image. This image comes pre-configured with ROCm 7.0, Ubuntu 24.04, ONNX Runtime 1.22, and PyTorch 2.8.0. This particular version is significant because it's the last ROCm version supported before the transition to MiGraphX, which, in this context, proved challenging to get working. Using this image ensures compatibility and avoids potential issues with newer, unsupported configurations. This saves you the hassle of manually installing and configuring these components, providing a ready-to-use environment.

3. Installing Essential System Packages

Within your newly created Distrobox container, install Git and FFmpeg using the following command:

sudo apt install git ffmpeg

Git is essential for cloning repositories and managing code, while FFmpeg is a powerful multimedia framework often required for video processing tasks. These are fundamental tools for many applications and workflows. Git allows you to easily download and update the application's code, while FFmpeg ensures that your application can handle various multimedia formats.

4. Locating the ONNX Runtime Package

Find the appropriate Python package for ONNX Runtime. This package is crucial for enabling GPU acceleration within your application. A likely location is the AMD ROCm repository, specifically the manylinux directory. For example, you might find it here (ROCM 7.0.2 in this example). However, it's crucial to navigate the repository yourself to ensure you select the correct version. The key is to match the package to your Python version (likely 3.12). This ensures that the ONNX Runtime library is compatible with your Python environment, preventing potential conflicts and errors. Matching the versions is critical for seamless integration and optimal performance.

5. Navigating to the Repository Folder

Open your terminal and navigate to the directory where you've cloned or extracted the application's repository. This is the working directory where you'll perform the subsequent steps. Making sure you're in the correct directory is a small step that can prevent a lot of confusion down the line. This ensures that all subsequent commands are executed in the appropriate context.

6. Creating a Python Virtual Environment

Create a virtual environment using the following command:

python -m venv venv

A virtual environment isolates your project's dependencies from the system-wide Python installation, preventing version conflicts. This is a best practice for Python development. It's like creating a separate little world for your project, where it has its own set of libraries and dependencies. This prevents your project from being affected by changes made to other projects on your system.

7. Activating the Virtual Environment

Activate the virtual environment using:

source venv/bin/activate

Once activated, your terminal prompt will typically change to indicate that you're working within the virtual environment. This is a crucial step as it ensures that subsequent pip commands install packages within the isolated environment. This directs the system to use the Python interpreter and libraries within the virtual environment, ensuring that your project's dependencies are correctly managed.

8. Uninstalling Default ONNX Runtime Packages

Uninstall any pre-existing ONNX Runtime packages to avoid conflicts:

pip uninstall onnxruntime onnxruntime-gpu

This step removes any default ONNX Runtime installations that might interfere with the ROCm-specific version you'll install later. Removing these conflicting packages ensures a clean installation process and avoids potential errors. This is like clearing the stage before the main performance, ensuring there are no interferences or distractions.

9. (Optional) Attempting to Install `onnxruntime-rocm`

You can try installing onnxruntime-rocm directly, but it may not be the matching version you need:

pip install onnxruntime-rocm

This is an optional step, and it's mentioned here because it's a common initial approach. However, it's important to note that this might not always result in the desired version. If it doesn't, proceed with the next steps. This step is like a quick shortcut that might work, but if it doesn't, we have a more reliable method to fall back on.

10. Removing `onnxruntime-gpu` from `requirements.txt`

Open the requirements.txt file and remove the onnxruntime-gpu entry. This ensures that the default GPU-enabled ONNX Runtime package is not installed during the next step. This prevents conflicts and ensures that only the ROCm-specific version is installed. This is like removing an unwanted guest from the party list, ensuring that only the right people are in attendance.

11. Installing Requirements

Install the remaining dependencies from the requirements.txt file:

pip install -r requirements.txt

This command installs all the necessary Python packages listed in the requirements.txt file, excluding onnxruntime-gpu (which you removed in the previous step). This ensures that your project has all the required dependencies except for the ONNX Runtime, which will be installed in the next step. This is like gathering all the tools needed for the job, except for the most specialized one, which we'll handle separately.

12. Installing the ROCm-Specific ONNX Runtime

Install the ONNX Runtime package you located in step 4 using the direct link:

pip install <your-link-to-onnx-from-amd-here>

Replace <your-link-to-onnx-from-amd-here> with the actual URL you copied earlier. This is the crucial step where you install the ROCm-enabled ONNX Runtime, enabling GPU acceleration on your AMD GPU. This ensures that the application uses your AMD GPU for its computations, significantly boosting performance.

13. Verifying ROCm Availability

Verify that ONNX Runtime can detect the AMD ROCm provider:

python -c "import onnxruntime; print(onnxruntime.get_available_providers())"

If the output includes AMD ROCm, it means the installation was successful. This is a critical verification step to ensure that ONNX Runtime is correctly configured to use your AMD GPU. If AMD ROCm is not listed, it indicates an issue with the installation, and you'll need to revisit the previous steps.

14. Running the Application with ROCm

Finally, start your application, specifying the rocm execution provider:

python3 run.py --execution-provider rocm

This command instructs the application to use the AMD ROCm provider for computations, leveraging your GPU for accelerated performance. This is the moment of truth, where you see your application running with the power of your AMD GPU. The --execution-provider rocm flag is what tells the application to use the ROCm backend for processing, which is essential for GPU acceleration.

By following these steps, you should be able to successfully run your application on your AMD GPU within a Linux environment. Remember to adapt the instructions to your specific setup and dependencies. Enjoy the boosted performance!

Conclusion

Running applications on AMD GPUs on Linux requires careful setup, but the performance gains are well worth the effort. This guide provides a comprehensive approach, from setting up a Distrobox container to installing the ROCm-specific ONNX Runtime. Remember to pay close attention to version compatibility and follow each step meticulously. By doing so, you can unlock the full potential of your AMD GPU on your Linux system.

For further information on ROCm and AMD GPU support, visit the official AMD ROCm Documentation.