How to run Minecraft Shaders on Linux running Wayland (1.21.4)

3 Minute Read

By: Kenny Blake

Published: December 16th, 2024 at 12:48 PM EST

Introduction

Running Minecraft with shaders on Linux under Wayland can be challenging, especially if you’re used to using OptiFine. While OptiFine has long been the go-to solution for improved performance and shader support, it often struggles with Wayland, leading to OpenGL errors and inconsistent performance.

Enter Iris and Sodium. These Fabric-based mods provide modern shader support (Iris) and performance optimization (Sodium) without relying on legacy OpenGL calls that trip up Wayland. Unlike OptiFine, Iris and Sodium are designed with modern rendering pipelines in mind, making them far more compatible with Linux’s evolving graphics stack.

A common point of confusion: Iris and Sodium do not work with Forge. They require the Fabric mod loader. This tutorial will guide you through installing Fabric headlessly, adding Iris and Sodium, and explaining why avoiding OptiFine on Wayland is the best path forward.

Why Not OptiFine?

OptiFine relies heavily on legacy OpenGL calls. Under Wayland, these calls often result in `OpenGL Error: 1282 (Invalid Operation)` messages and shader compilation issues. While you can sometimes mitigate this by running Minecraft under XWayland, it’s a compromise. Iris and Sodium, on the other hand, offer modern, Wayland-friendly shader pipelines out of the box, making them the superior choice for Linux users who want to use wayland.

Installation Process (Fabric, Iris & Sodium)

We will install the Fabric mod loader headlessly, then add Iris and Sodium. No GUI installers, no OptiFine—just a clean, Wayland-friendly shader setup.

Ensure Java is Installed:You have a modern Java installed:
```
java --version
```
Java 17+ is recommended. In this guide, I used Redhat's OpenJDK Version 21.
- Fedora (My Distro)/ RHEL / CentOS:
```
sudo dnf install java-17-openjdk
```
- Debian / Ubuntu:
```
sudo apt-get update && sudo apt-get install openjdk-17-jdk
```
- Arch Linux:
```
sudo pacman -S jdk17-openjdk
```
Download the Fabric Installer:Grab the Fabric installer `.jar` from the Fabric website. Once downloaded, run:
```
java -jar fabric-installer-(fabric-version).jar client -mcversion 1.21.4 -downloadMinecraft
```
Replace (fabric-version) with your desired Minecraft version.
Add Iris and Sodium:Download Iris and Sodium `.jar` files from Modrinth or their official websites:
- Iris: https://modrinth.com/mod/iris
- Sodium: https://modrinth.com/mod/sodium
Then place them into the `mods` folder:
```
mkdir -p ~/.minecraft/mods
cp /path/to/iris-fabric.jar ~/.minecraft/mods/
cp /path/to/sodium-fabric.jar ~/.minecraft/mods/
```

Add Shader Packs: Create a `shaderpacks` folder and add your shader `.zip`:

mkdir -p ~/.minecraft/shaderpacks
cp /path/to/shaderpack.zip ~/.minecraft/shaderpacks/

Launch Minecraft with Fabric: Open your minecraft launcher, and click `"`fabric-loader-(your version)`"` and run it. Iris and Sodium will be active, and you can enable shaders in Video Settings → Shader Packs.

Conclusion

OptiFine’s OpenGL errors can make shaders on Wayland a frustrating experience. By embracing Fabric-based mods like Iris and Sodium, you gain compatibility, stability, and performance—no complex workarounds required.

With this setup, you’ll enjoy a smooth, shader-rich Minecraft experience on Wayland without the headaches caused by legacy rendering paths. Iris and Sodium represent the future of Linux shader modding, making OptiFine obsolete in Wayland environments.