Installation

Aqueous separates the compositor and configuration tools from the desktop session and shell. The core contains aqueous, aqueousctl, aqueous-config, and the matching private wlroots library. Desktop packages add session startup, Welcome, portals, and optional shell integrations.

These instructions describe the current source packaging. Repository releases can lag behind; package names in a source recipe do not establish that a new package has been published to the AUR or a binary repository.

Arch Linux

CachyOS repositories (Recommended)

shelly
pacman

shelly -Is aqueous

sudo pacman -S aqueous

AUR

shelly -Ia aqueous

yay -S aqueous

paru -S aqueous

To build the Arch package from a checkout:

git clone https://github.com/Seafoam-Labs/Aqueous.git
cd Aqueous
makepkg -s

After a successful build, install the desktop components together, leaving the optional shell presets for Welcome to select. In the same Bash shell:

mapfile -t packages < <(makepkg --packagelist | awk '!/\/aqueous-shell-/')
sudo pacman -U "${packages[@]}"

Shell and package variants

Package or recipe	Purpose
`aqueous-core`	Stable compositor, CLI, configuration helper, and private wlroots; no desktop session or shell.
`aqueous` from the root `PKGBUILD`	Complete stable desktop composed from core, session, Welcome, portal, and shell integrations.
`PKGBUILD-bin`	Matching release component archives; use a generated recipe with release checksums.
`aqueous-core-git`	Development core alongside stable Aqueous, with suffixed commands and private configuration.
`aqueous-desktop-git`	Optional Git desktop, login entry, Welcome, portal, and integrations around the matching Git core.

Shell integration packages contain conditional services. The explicit aqueous-shell-pearl, aqueous-shell-dms, and aqueous-shell-noctalia presets also install their shell; Git desktops use the corresponding -git presets. Welcome offers Pearl, DMS, Noctalia, or Nothing. Installing an integration alone does not select or start a shell.

The old combined Git, Intel, DMS, and Noctalia package recipes have been retired. Existing legacy packages and personal configurations are not automatically renamed or migrated. Current x86_64 package builds target x86-64-v3 on Intel and AMD; older CPUs need a custom lower-target build. Aarch64 uses its baseline.

The separate packaging/arch/aqueous/PKGBUILD is compositor-only; unlike the root recipe, it does not install the full desktop.

Build a co-installable Git desktop

From a checkout, build both recipes and install the core and desktop components together. In Bash:

repo=$PWD
core="$repo/packaging/arch/aqueous-core-git"
desktop="$repo/packaging/arch/aqueous-desktop-git"

(cd "$core" && makepkg -s) && (cd "$desktop" && makepkg -s)

Continue only if both builds succeeded:

mapfile -t core_packages < <(cd "$core" && makepkg --packagelist)
mapfile -t desktop_packages < <(
    cd "$desktop" && makepkg --packagelist | awk '!/\/aqueous-shell-/'
)
sudo pacman -U "${core_packages[@]}" "${desktop_packages[@]}"

The desktop recipe also builds optional shell presets; the filter leaves those for an explicit choice in Welcome. Use a normal Arch build environment and resolve the matching core dependency before building the desktop. These VCS recipes fetch upstream Git, rather than building unpublished local changes. See the Git packaging guide for dependency and isolated-build details.

Select Aqueous-Git at login. It uses aqueous-git, aqueousctl-git, and aqueous-config-git, with configuration under ~/.config/aqueous-git/. Stable Aqueous continues to use ~/.config/aqueous/. See Desktop selection and Git sessions.

Fedora

On a mutable Fedora installation, run the installer as your normal user from the repository checkout:

bash scripts/fedora-install.sh

It fetches current upstream master into a separate build directory, installs build dependencies through DNF, and builds a local desktop RPM. It uses sudo for package transactions. Fedora must provide Zig 0.16 or newer and wayland-protocols 1.49 or newer.

Useful options include --build-only, --skip-deps, and --core-only. Core-only mode produces an aqueous-core RPM without desktop session dependencies. The default desktop RPM retains the legacy aqueous-git name; it is distinct from the co-installable Arch Git packaging above. --dms-git explicitly enables the DMS development COPR and cannot be combined with --core-only.

The installer does not support Atomic desktops such as Silverblue/Kinoite or bootc hosts. Existing user configuration is retained; edited system defaults may receive .rpmnew files. See the Fedora source guide for updating, removal, and package prerequisites.

Gentoo

The repository includes an installer that can install dependencies, build the pinned compositor stack and settings helper, install the session, and verify the result:

git clone https://github.com/Seafoam-Labs/Aqueous.git
cd Aqueous
sudo scripts/gentoo-install.sh all

Use deps, build, or install instead of all to run one stage. For the shell-independent core, put --core-only before the stage, for example sudo scripts/gentoo-install.sh --core-only all. Existing files under /etc are preserved; changed packaged defaults are written beside them with an .aqnew suffix.

NixOS

The nix/ directory provides a package, overlay, and NixOS module. From a configuration repository, import both the module and overlay:

{
  imports = [ /path/to/Aqueous/nix/module.nix ];
  nixpkgs.overlays = [ (import /path/to/Aqueous/nix/overlay.nix) ];

  programs.aqueous = {
    enable = true;
    package = pkgs.aqueous;
    shell = "noctalia"; # noctalia | dms | pearl | none
  };
}

Choose programs.aqueous.shell explicitly. DMS and Pearl also require programs.aqueous.shellPackage; Noctalia defaults to pkgs.noctalia-shell. Use "none" for a managed session without a shell. The old noctalia.enable setting is deprecated, and conflicting choices fail validation. An existing per-user session.toml takes precedence over the system default.

programs.aqueous.welcome.enable optionally adds Welcome. Its package-install workflow requires Shelly to be available separately. Installing pkgs.aqueousCore alone installs the tools without enabling the session module.

Build from source

Building requires Zig 0.16 or newer, wayland-protocols 1.49 or newer, wlroots 0.20 build dependencies, libxkbcommon, libinput, libevdev, pixman, Vulkan headers and loader, Meson, Ninja, pkg-config, and glslang. XWayland builds also need the Xwayland executable. Man-page builds use scdoc.

The repository helper builds the patched wlroots render hook and stages aqueous and aqueousctl under bin/:

git clone https://github.com/Seafoam-Labs/Aqueous.git
cd Aqueous
scripts/build-compositor.sh

For a direct development build:

cd compositor
scripts/build-wlroots-render-hook.sh
export PKG_CONFIG_PATH="$PWD/.deps/wlroots-render-hook/lib/pkgconfig"
zig build -Doptimize=ReleaseSafe -Dxwayland -Dllvm

Useful build switches are:

Option	Purpose
`-Dxwayland=true`	Build embedded XWayland support.
`-Dvulkan-effects=false`	Diagnostic build without Aqueous blur or rounded corners; still requires the pinned patched wlroots.
`-Danimations=false`	Compile out compositor-side placement and workspace motion.
`-Dman-pages=true`	Build and install manual pages when `scdoc` is available.
`-Dexternal-policy=true`	Build the retired River external-policy path for compatibility testing only.

Starting a session

Select Aqueous from the display manager’s Wayland session list.
The packaged wrapper launches Aqueous through UWSM, exports the live WAYLAND_DISPLAY and optional XWayland environment, and starts the graphical-session services and portals.
On a fresh component desktop, Welcome offers a shell choice. Select Pearl, DMS, Noctalia, or Nothing, then complete setup. Existing selections and personal configuration are retained.

Use Desktop selection for Welcome activation, Git-session shell switching, and recovery. Settings are supplied by Pearl and the canonical configuration helper.

To run a nested development session inside another Wayland compositor:

./launch_aqueous.sh

The launcher starts Aqueous and Pearl in the nested display, using pearl or pearl-git when available. Set AQUEOUS_COMPOSITOR_BIN=/path/to/aqueous to select a build and AQUEOUS_PEARL_CMD to override the shell command. Nested sessions use Alt for the compositor modifier so they do not compete with the host’s Super bindings. Default logs are /tmp/aqueous.log and /tmp/pearl.log.

Runtime switches

aqueous -help lists the complete runtime interface. Common development options include -c <command>, -log-level debug, -no-xwayland, and -xwayland-scaling native. Shipped sessions use the internal policy; external and comparison policy modes require the compatibility build option above.