Quickstart

Get Zirconium up and running in minutes with bootc rebase or ISO installation

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

Rebase from Fedora Atomic

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.

ISO installation

For fresh installations or systems not running Fedora Atomic, use the Zirconium ISO.

1. Download the ISO

   Choose the ISO for your hardware:

   AMD64 (x86_64)

   • AMD/Intel GPUs (Checksum)
   • NVIDIA GPUs (Checksum)

   ARM64

   • AMD/Intel GPUs (Checksum)
   • NVIDIA GPUs (Checksum)
2. Verify the checksum (optional but recommended)

   Verify the integrity of your download:

   sha256sum -c zirconium-*.iso-CHECKSUM
   
3. Create bootable media

   Use a tool like Fedora Media Writer, Rufus (Windows), or dd to create a bootable USB drive:

   # Example with dd (Linux)
   sudo dd if=zirconium-amd64.iso of=/dev/sdX bs=4M status=progress
   

   Replace /dev/sdX with your USB drive’s device path. This will erase all data on the drive.

4. Boot from the USB drive

   Restart your computer and boot from the USB drive. You may need to adjust your BIOS/UEFI boot order or use a boot menu key (usually F12, F2, or Del).

5. Follow the installation wizard

   The Anaconda installer will guide you through:

   • Disk partitioning
   • User account creation
   • Network configuration
   • Timezone settings

   The installer will automatically run this bootc command during installation:

   bootc switch --mutate-in-place --transport registry \
     ghcr.io/zirconium-dev/zirconium:latest
   
6. Reboot and log in

   After installation completes, remove the USB drive and reboot. You’ll be greeted by DankMaterialShell.

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:

   • Discord server
   • GitHub repository
   • Report issues

Troubleshooting

System won't boot after rebase

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

NVIDIA drivers not working

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

Display not working on ARM64

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