入 // BEGINNER INSTALLATION

INSTALLRYOKU.

Add Ryoku to an existing NixOS system. New to flakes? Follow the steps below. Starting from a USB instead? See the test ISO option.

Difficulty: Beginner
Platform: NixOS x86_64
Method: Nix flakes
Installer: Ryoku NixOS

00 // BEFORE YOU START

You only need a normal NixOS install.

You should already be booted into NixOS, connected to the internet, and able to use sudo. Your normal configuration should exist at /etc/nixos/configuration.nix.

Already using flakes? Skip straight to Preview Ryoku. You do not need to convert your system again.

01 // ENABLE FLAKES

Turn on the Nix features Ryoku needs.

01.A

Open your NixOS configuration.

sudo nano /etc/nixos/configuration.nix

01.B

Add this inside the main `{ }` block.

nix.settings.experimental-features = [
  "nix-command"
  "flakes"
];

Do not paste it above the opening { or below the final }.

01.C

Save and close Nano.

Ctrl + OEnterCtrl + X

01.D

Apply the change.

sudo nixos-rebuild switch

If this finishes successfully, flakes are enabled.

02 // CREATE FLAKE.NIX

Make the system itself flake-based.

Create one new file alongside your existing NixOS configuration. Your existing configuration.nix and hardware-configuration.nix stay where they are.

02.A

Create the file.

sudo nano /etc/nixos/flake.nix

02.B

Paste this beginner flake.

{
  description = "My NixOS system";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
  };

  outputs = { nixpkgs, ... }: {
    nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";

      modules = [
        ./configuration.nix
      ];
    };
  };
}

This creates a flake target called nixos, which is why the rebuild command below ends in #nixos.

02.C

Save it.

Ctrl + OEnterCtrl + X

03 // TEST YOUR FLAKE

Make sure NixOS rebuilds before adding Ryoku.

sudo nixos-rebuild switch --flake /etc/nixos#nixos

Stop here if this fails. Ryoku should only be installed after your own flake can rebuild successfully. Fix the NixOS error first rather than stacking another change on top.

04 // PREVIEW RYOKU

See what the installer will do first.

Run this as your normal user. Do not put sudo in front of it; the installer asks for elevated access only when it actually needs it.

nix run github:aethctl/Ryoku-on-NixOS/main#install -- --dry-run

The same guided screens open in preview mode. After review, the backend prints the proposed configuration without installing Ryoku.

05 // INSTALL

Open the guided installer.

nix run github:aethctl/Ryoku-on-NixOS/main#install

The guided installer lets you choose Hyprland or Niri, Chromium or Firefox, Fish or Zsh, and optional apps. Use arrow keys to move, Enter to continue, Space to toggle apps and Esc to go back.

The installer integrates Ryoku into your existing flake, builds a new NixOS generation, and switches only after that build succeeds.

Ryoku does not reinstall NixOS. It does not repartition your drives, replace your bootloader, or take ownership of your hardware-specific GPU configuration.

06 // UPDATE LATER

Future updates are one command.

ryoku update

Ryoku advances its Nix flake input, builds a new NixOS generation, and switches to it. You do not need to reinstall or clone the repository again.

07 // IF SOMETHING FAILS

Do not panic-reinstall.

NixOS gives us a much better failure model than destructive package replacement. A failed build should be diagnosed from the exact error first.

Useful support information: copy the final error from your terminal, say which step of this guide you were on, and include whether your system rebuilt successfully with /etc/nixos#nixos before Ryoku.

Discord support ↗ GitHub issues ↗