aethctl/Ryoku-on-NixOS

Ryoku on NixOS

力と美のために

The Ryoku you already know, made declarative for NixOS.

Ryoku on NixOS is the official NixOS port of Ryoku, a complete Wayland desktop with deep customisation, integrated applications and the best and most expansive ecosystem to ever be made on a shell.

Website · Install on NixOS · Installer ISO · Discord · Documentation · Upstream Ryoku

Beauty on the surface. Nix underneath.

The shell, Hub, launcher, RyoStore, theming and Ryoku applications are identical to its Arch counterpart while NixOS specific packaging, modules, system bridges, installer behavior and updates remain declarative.

v1 is currently in active beta. The existing NixOS install script is the recommended route however, the bootable ISO is available for testing from GitHub Releases but it will erase the selected disk during installation as is currently doesnt support manual partitioning.

Desktop. Aesthetic by default and heavily customisable.	App Launcher. Apps, commands, files, packages, calculator and more in one launcher.
Controls. Session, connectivity, sound, brightness, media and power in one sidebar.	Profile. The most customizable configuration profile page in any shell
Ryoku Hub. System information, settings and Ryoku specific controls in one place.	Matugen. No matter the wallpaper, components recolour themselves around it.

Ryoku is designed to be incredibly customizable out of the box with the easy to use Ryostore and Settings page

Ryoku's base code and configs are the same as upstream, this repository is simply the NixOS adaptation. Packaging, module integration, installer and update behavior, service wiring, compatibility fixes and Nix specific runtime bridges.

That gives the same desktop two different system foundations:

Ryoku is more than the shell. The desktop is built from a set of focused tools that share the same visual and interaction language.

There are two installation paths.

For an existing flake-based NixOS system, start the guided installer as your normal user

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

Choose your compositor, browser, shell and optional apps, then review the generated changes before installation begins.

The installer:

• adds Ryoku to your existing flake,
• creates the ryoku.nix modules,
• updates flake.lock,
• builds a new generation,
• switches to the new generation only after the build succeeds,
• restores the previous configuration files if the integration fails.

For custom flake paths, multi-host setups and manual integration, see the NixOS guide.

The bootable Ryoku on NixOS installer ISO is currently in pre-release testing ahead of v1. It is intended to become the primary path for fresh installations.

View installer ISO releases →

Testing warning: installation will erase the selected disk. Back up anything important before using a pre-release ISO.

Ryoku is x86_64 only and boots in UEFI mode. The session is Wayland on Hyprland or niri, with the GPU-composited Ryoku shell on top. The installer refuses a machine with Secure Boot on (Limine ships unsigned) unless you have enrolled your own keys, and there is no 32-bit build and no legacy BIOS path.

The repository is intentionally split between /ryoku and /nix. Shared desktop features are located in /ryoku. Nix specific files, modules and compatability layers live in nix/.

The Nix layer packages the major Ryoku components independently rather than treating the desktop as one wrapper. The root flake exposes the shell, Hub, CLI, Ryostore, Ryotunes, Ryogami, RyoMotion, helper packages, compositor integration and the combined bundle as separate outputs.

This is a maintained platform port, not a one-time source translation. Upstream changes are reviewed and are ported within 2 days of upstream release.

1. Shared desktop and application changes stay in ryoku/ whenever possible.
2. Arch specific packages, servicse and filesystem assumptions are replaced with Nix packages, NixOS modules or narrow runtime bridges.
3. Bugs that also affect upstream Ryoku are fixed upstream when practical, fixes that only exist because of NixOS being NixOS stay in this repo.
4. Visible runtime changes are tested on NixOS before they are released.

The detailed ownership rules and sync workflow live in docs/maintenance.md.

The public flake makes the core port buildable through one entry point

nix flake check

Its checks build the main runtime packages, QML modules, desktop integration, installer and materializer, and run focused installer/parser checks. CI adds shell linting, QML linting, Go tests, installer safety checks and targeted integration guards.

For compositor, display, audio, GPU or installer behavior, a green CI run is not treated as runtime proof. Pull requests should record the machine/runtime test that was actually performed.

Ryoku on NixOS is actively maintained and contributions are welcome.

• Join the Ryoku Discord for installation help, testing and development discussion.
• Browse open issues for current work.
• Start with a good first issue if you want a bounded first contribution.
• Read CONTRIBUTING.md for the development workflow, testing expectations and upstream/NixOS ownership boundary.
• Read the performance roadmap for measured shell-performance work that needs contributors.

Testing is useful too. Hardware-facing changes cannot be proven by CI alone, so real reports from different GPUs, compositors and machines materially improve the port.

Clone the repository and enter the development shell:

nix develop

Run Ryoku directly from a development checkout:

nix run .#ryoku-dev

Useful public flake outputs include:

.#install
.#ryoku-dev
.#ryoku-materialize

See docs/README.md for the documentation map and docs/structure.md for the repository layout.

Ryoku on NixOS is the NixOS port of Ryoku.

Ryoku was created by Neur0map. The NixOS port keeps upstream desktop behavior close while adapting system integration to NixOS.

Full attribution is available in NOTICE.

Ryoku is released under the GNU GPL v3.