Skip to content
IRONLINUX
Download

Docs.

On this page

Requirements

  • A 64-bit Intel or AMD PC, or a Raspberry Pi 4.
  • Secure Boot turned off.
  • A USB stick of 2 GB or more (or a 16 GB+ microSD card for the Pi).
  • Tested configuration: 2 CPU cores, 4 GB memory, 20 GB disk, in QEMU/KVM. Iron Linux has not yet been tested on physical hardware. See Compatibility.

Write the image

Windows or macOS: use balenaEtcher, or Rufus in DD image mode.

Linux: find the USB stick with lsblk, then write the ISO. This erases everything on the target device.

Terminal
sudo dd if=iron-linux-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync

Boot and try

  1. Turn off Secure Boot in your firmware settings.
  2. Start the computer from the USB stick. The boot menu key varies by manufacturer (often F12, F11 or Esc).
  3. Choose Try or Install Iron Linux. If the screen stays black or looks wrong, restart and choose Iron Linux (Safe Graphics).
  4. Log in with username iron and password live.

Install

Click Install Iron Linux in the panel, or press Super + I. The installer walks through:

  1. Language and location
  2. Keyboard layout
  3. Partitions. Erase disk is the tested option.
  4. Your username and password
  5. Summary, then install

Restart when it finishes and remove the USB stick.

Setup script

Build Your Iron creates a setup script with the drivers, apps and settings you chose. The installer doesn't read it: run it yourself after installing.

  1. Read the script. It only uses apt, flatpak and systemctl.
  2. Connect to the internet.
  3. Run it from your own account, then restart.
Terminal
bash iron-setup-my-iron.sh

Your profile (.json) can be imported back into Build Your Iron to change it later.

Shortcuts

SuperEnterTerminal
SuperSpaceApp launcher
SuperDApp launcher
SuperEFiles
SuperBFirefox
SuperSIron Settings
SuperIInstaller
SuperVClipboard history
AltTabNext window
AltShiftTabPrevious window
AltF4Close window
SuperQClose window
Super←Snap left
Super→Snap right
Super↑Maximize
Super↓Restore
SuperHMinimize
Super1–4Go to workspace
SuperShift1–4Move window to workspace
PrintScreenshot
ShiftPrintScreenshot a region
SuperLLock
SuperXPower menu
SuperShiftCReload desktop config

Software

Iron Linux uses Debian's own repositories. Anything packaged for Debian installs normally.

Terminal
sudo apt update
sudo apt install vlc
sudo apt install ./package.deb

For Flathub apps, enable Flatpak (Build Your Iron can do this), then flatpak install flathub <app-id>.

Raspberry Pi 4

The Pi has its own image and guide: Iron Linux on Raspberry Pi 4.

Virtual machines

QEMU/KVM is the tested setup. SPICE and VMware guest tools are included.

Terminal
qemu-img create -f qcow2 iron.qcow2 20G
qemu-system-x86_64 -enable-kvm -cpu host -m 4096 -smp 2 \
  -drive file=iron.qcow2,format=qcow2,if=virtio \
  -cdrom iron-linux-amd64.iso -boot d

Troubleshooting

The USB stick doesn't boot

Check Secure Boot is off. If you used Rufus, write the image again in DD mode.

Black screen after the boot menu

Choose Iron Linux (Safe Graphics).

Wi-Fi

Click the network icon in the panel, or run nmcli dev wifi connect "NAME" password "PASSWORD".

Sound

Use the volume control in the panel or your keyboard's volume keys. For a full mixer: sudo apt install pavucontrol.

Something else

Open an issue on GitHub with your hardware and what happened.

Build from source

Images are built with Debian live-build. Use a disposable Debian 13 VM or container as the build host.

Terminal
git clone https://github.com/crossainthero-lab/IronLinux.git
cd IronLinux
sudo ./scripts/bootstrap-build-host.sh
sudo ./build.sh                       # PC ISO
sudo ./scripts/build-rpi4-arm64.sh    # Raspberry Pi 4 image