Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/zirconium-dev/zirconium/llms.txt

Use this file to discover all available pages before exploring further.

​
Get started with Zirconium

Zirconium can be installed in two ways: by rebasing from an existing Fedora Atomic system, or by installing from a bootable ISO. Choose the method that works best for you.

​
Prerequisites

Before installing Zirconium, make sure you have:
  • For rebase method: An existing Fedora Atomic-based system (Silverblue, Kinoite, Bluefin, Aurora, etc.)
  • For ISO method: A USB drive (4GB or larger) and a tool to create bootable media
  • Hardware requirements:
    • x86_64 (AMD64) or ARM64 CPU
    • 4GB RAM minimum (8GB recommended)
    • 25GB free disk space
  • GPU compatibility:
    • AMD/Intel GPUs work out of the box
    • NVIDIA GTX 16xx or RTX series requires the -nvidia variant
NVIDIA support requires disabling Secure Boot. The kernel module is currently unsigned. See the GPU variants guide for details.

​
Installation methods

If you already have a Fedora Atomic system installed, rebasing to Zirconium is the fastest method.
1

Open a terminal

Launch your terminal application. You’ll need to run commands with sudo privileges.
2

Run the bootc switch command

For AMD/Intel GPUs:
sudo bootc switch ghcr.io/zirconium-dev/zirconium:latest
For NVIDIA GPUs (GTX 16xx or RTX series):
sudo bootc switch ghcr.io/zirconium-dev/zirconium-nvidia:latest
This command downloads the Zirconium container image and prepares it as your next boot target.
3

Reboot your system

Once the switch completes, reboot to start using Zirconium:
systemctl reboot
4

Log in and enjoy

After rebooting, you’ll be greeted by the DankMaterialShell greeter. Log in to experience your new Niri-powered desktop.
The rebase preserves your home directory and user data. Your previous system remains available as a rollback option in the boot menu.

​
First steps after installation

Once you’ve logged into Zirconium, here’s what to do next:
1

Learn the Niri basics

Niri uses a scrollable tiling layout. Some essential keybindings:
  • Super + Enter: Open terminal
  • Super + D: Application launcher
  • Super + Q: Close window
  • Super + H/L: Navigate between windows
  • Super + Shift + H/L: Move windows
See the Niri configuration guide for a complete list of keybindings.
2

Install applications

Zirconium supports multiple package management methods:
  • Flatpak (recommended for GUI apps): flatpak install flathub <app>
  • Homebrew (for CLI tools): brew install <package>
  • Layering (for system packages): rpm-ostree install <package>
Learn more in the operations maintenance guide.
3

Customize your setup

Niri and DankMaterialShell configurations live in:
  • ~/.config/niri/config.kdl: Niri window manager settings
  • ~/.config/dms/: DankMaterialShell configuration
Consider using chezmoi (pre-installed) to manage your dotfiles across systems.
4

Join the community

Get help, share your setup, and contribute:

​
Troubleshooting

If Zirconium fails to boot, you can roll back to your previous system:
  1. At the GRUB boot menu, select the previous deployment
  2. Once booted, pin your working deployment: 
    sudo ostree admin pin 0
  3. Report the issue on GitHub
Ensure you:
  1. Used the -nvidia variant image
  2. Disabled Secure Boot in your BIOS/UEFI
  3. Rebooted after the initial installation
Check driver status:
lsmod | grep nvidia
nvidia-smi
ARM64 support varies by hardware. Check:
  1. Your device is using a supported SoC
  2. Required firmware is present in /lib/firmware
  3. Kernel messages for errors: dmesg | grep -i display

​
Next steps

ISO installation

Install from a bootable ISO image

GPU variants

Choose the right image for your GPU

Configuration

Customize Niri and DankMaterialShell

Building custom images

Build your own customized Zirconium image

Build docs developers (and LLMs) love

Get started for freeTalk to us