DEV Community

Zeb
Zeb

Posted on

Building Desktop Apps with Dioxus on Linux

#rust #linux #webdev

This guide will walk you through installing Rust, Dioxus, necessary native dependencies, and fixing the infamous black screen bug on Linux.

✅ Prerequisites

You’ll need a Linux system (Ubuntu, Debian, Arch, etc.) and basic terminal knowledge.

1. 🦀 Install Rust

Install Rust using rustup, the official toolchain installer:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh Then restart your shell or run:
Enter fullscreen mode Exit fullscreen mode 
source $HOME/.cargo/env
Enter fullscreen mode Exit fullscreen mode

Confirm it works:

rustc --version cargo --version
Enter fullscreen mode Exit fullscreen mode

2. 📦 Install System Dependencies

Dioxus desktop apps use GTK and other native libraries. These are not bundled, so you need to install them yourself.

On Debian/Ubuntu/Pop!_OS:

sudo apt update sudo apt install \ libgtk-3-dev \ libwebkit2gtk-4.1-dev \ libsoup-3.0-dev \ libxdo-dev \ build-essential \ pkg-config \ libssl-dev
Enter fullscreen mode Exit fullscreen mode

If you hit more linker errors, read the message carefully and install the -dev package for the missing lib.

3. ⚙️ Install Dioxus CLI

Install cargo-binstall so you can install Dioxus CLI tool.

curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
Enter fullscreen mode Exit fullscreen mode

Dioxus has a CLI tool to streamline development:

cargo binstall dioxus-cli
Enter fullscreen mode Exit fullscreen mode

Then verify:

dx --help
Enter fullscreen mode Exit fullscreen mode

4. 🧪 Create and Serve Your App

Start a new app:

dx new hot_dog cd hot_dog dx serve
Enter fullscreen mode Exit fullscreen mode

5. 🐛 Fix: Black Screen in Dioxus Desktop

If your app launches but displays a black window, you're likely hitting a WebKit compositing bug on Linux.

Fix it with this environment variable in the main program loop:

//main.rs fn main() { std::env::set_var("WEBKIT_DISABLE_COMPOSITING_MODE", "1"); dioxus::launch(App); }
Enter fullscreen mode Exit fullscreen mode

Or add it to your shell config:

echo 'export WEBKIT_DISABLE_COMPOSITING_MODE=1' >> ~/.bashrc source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

✅ Done!

You’re now set up to build performant, native-feeling desktop GUIs using Rust and Dioxus.

For more:
👉 https://dioxuslabs.com/guide/

Top comments (0)