Noctalia

quiet by design

A sleek and minimal desktop shell thoughtfully crafted for Wayland, built with Quickshell.

Features a modern modular architecture with a status bar, notification system, control panel, comprehensive system integration, and more — all styled with a warm lavender palette, or your favorite color scheme!

Preview

---

⚠️ Note:
This shell currently supports Niri and Hyprland compositors. For other compositors, you will need to implement custom workspace logic in the CompositorService.

---

Features

• Status Bar: Modular bar with workspace indicators, system monitors, clock, and quick access controls.
• Workspace Management: Dynamic workspace switching with visual indicators and active window tracking.
• Notifications: Rich notification system with history panel.
• Application Launcher: Stylized launcher with favorites, recent apps, and special commands (calc, clipboard).
• Side Panel: Quick access panel with media controls, weather, power profiles, and system utilities.
• Settings Panel: Comprehensive configuration interface for all shell components and preferences.
• Lock Screen: Secure lock experience with PAM authentication, time display, and animated background.
• Audio Integration: Volume controls, media playback, and audio visualizer (cava-based).
• Connectivity: WiFi and Bluetooth management with device pairing and network status.
• Power Management: Battery monitoring, brightness control, and power profile switching.
• System Monitoring: CPU, memory, and network usage monitoring with visual indicators.
• Tray System: Application tray with menu support and system integration.
• Background Management: Wallpaper management with effects and dynamic theming support.
• Color Schemes: Catppuccin, Dracula, Gruvbox, Noctalia, Nord, Rosépine, Solarized, Tokyo night or generated from your wallpaper.
• Scaling: Per monitor scaling for maximum control.

---

Dependencies

Required

• quickshell-git - Core shell framework
• ttf-roboto - The default font used for most of the UI
• inter-font - The default font used for Headers (ex: clock on the LockScreen)
• ttf-material-symbols-variable-git - Icon font for UI elements
• gpu-screen-recorder - Screen recording functionality
• brightnessctl - For internal/laptop monitor brightness
• ddcutil - For desktop monitor brightness (might introduce some system instability with certain monitors)

Optional

• cliphist - For clipboard history support
• matugen - Material You color scheme generation
• cava - Audio visualizer component
• wlsunset - To be able to use NightLight

There are 2 more optional dependencies.
Any polkit agent to be able to use the ArchUpdater widget.
And also any xdg-desktop-portal to be able to use the "Portal" option from the screenRecorder.

---

Quick Start

Installation

Arch Linux

AUR

You can install Noctalia from the AUR. This method will install the shell system-wide.

paru -S noctalia-shell

If you want the latest development version directly from the git repository, you can use the noctalia-shell-git package:

paru -S noctalia-shell-git

This will always build the most recent commit from the Noctalia repository. Note that it may be less stable than the release version.

Manual Installation

This method installs the shell to your local user configuration.

# Install Quickshell
paru -S quickshell-git
# Download and install Noctalia (latest release)
mkdir -p ~/.config/quickshell && curl -sL https://github.com/noctalia-dev/noctalia-shell/releases/latest/download/noctalia-latest.tar.gz | tar -xz --strip-components=1 -C ~/.config/quickshell

Nix

Nix Installation

You can run Noctalia directly using the nix run command:

nix run github:noctalia-dev/noctalia-shell

Alternatively, you can add it to your NixOS configuration or flake:

Step 1: Add Quickshell and Noctalia flakes to your flake.nix:

{
  description = "Example Nix flake with Noctalia + Quickshell";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    noctalia = {
      url = "github:noctalia-dev/noctalia-shell";
      inputs.nixpkgs.follows = "nixpkgs";
    };

    quickshell = {
      url = "github:outfoxxed/quickshell";
      inputs.nixpkgs.follows = "nixpkgs";
      inputs.quickshell.follows = "quickshell"
    };
  };

  outputs = { self, nixpkgs, noctalia, quickshell, ... }:
   {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      modules = [
        ./configuration.nix
      ];
    };
  };
}

Step 2: Add the packages to your configuration.nix:

{
  environment.systemPackages = with pkgs; [
    inputs.noctalia.packages.${system}.default
    inputs.quickshell.packages.${system}.default
  ];
}

Usage

Nix/AUR

The following commands apply to the Nix flake and also the AUR package installation.

Action	Command
Start the Shell	noctalia-shell
Toggle Application Launcher	noctalia-shell ipc call launcher toggle
Toggle Side Panel	noctalia-shell ipc call sidePanel toggle
Open Clipboard History	noctalia-shell ipc call launcher clipboard
Open Calculator	noctalia-shell ipc call launcher calculator
Increase Brightness	noctalia-shell ipc call brightness increase
Decrease Brightness	noctalia-shell ipc call brightness decrease
Increase Output Volume	noctalia-shell ipc call volume increase
Decrease Output Volume	noctalia-shell ipc call volume decrease
Toggle Mute Audio Output	noctalia-shell ipc call volume muteOutput
Toggle Mute Audio Input	noctalia-shell ipc call volume muteInput
Toggle Power Panel	noctalia-shell ipc call powerPanel toggle
Toggle Idle Inhibitor	noctalia-shell ipc call idleInhibitor toggle
Toggle Settings Window	noctalia-shell ipc call settings toggle
Toggle Lock Screen	noctalia-shell ipc call lockScreen toggle
Toggle Notification History	noctalia-shell ipc call notifications toggleHistory

Manual install

The following commands apply to a manual installation.

Action	Command
Start the Shell	qs
Toggle Application Launcher	qs ipc call launcher toggle
Toggle Side Panel	qs ipc call sidePanel toggle
Open Clipboard History	qs ipc call launcher clipboard
Open Calculator	qs ipc call launcher calculator
Increase Brightness	qs ipc call brightness increase
Decrease Brightness	qs ipc call brightness decrease
Toggle Power Panel	qs ipc call powerPanel toggle
Toggle Idle Inhibitor	qs ipc call idleInhibitor toggle
Toggle Settings Window	qs ipc call settings toggle
Toggle Lock Screen	qs ipc call lockScreen toggle
Toggle Notification History	qs ipc call notifications toggleHistory

Configuration

Access settings through the side panel (top right button) to configure weather, wallpapers, screen recording, audio, network, and theme options.
Configuration is usually stored in ~/.config/noctalia
If you upgrade from v1, you can delete the old configuration folder at ~/.config/Noctalia (with capital N)

Application Launcher

The launcher supports special commands for enhanced functionality:

• >calc - Simple mathematical calculations
• >clip - Clipboard history management

---

Theme Colors

Color Role	Color	Description
Primary	#c7a1d8	Soft lavender purple
On Primary	#1a151f	Dark text on primary
Secondary	#a984c4	Muted lavender
On Secondary	#f3edf7	Light text on secondary
Tertiary	#e0b7c9	Warm pink-lavender
On Tertiary	#20161f	Dark text on tertiary
Surface	#1c1822	Dark purple-tinted surface
On Surface	#e9e4f0	Light text on surface
Surface Variant	#262130	Elevated surface variant
On Surface Variant	#a79ab0	Muted text on surface variant
Error	#e9899d	Soft rose red
On Error	#1e1418	Dark text on error
Outline	#4d445a	Purple-tinted outline
Shadow	#120f18	Deep purple-tinted shadow

---

Advanced Configuration

Recommended Compositor Settings

For Niri:

window-rule {
    geometry-corner-radius 20
    clip-to-geometry true
}

layer-rule {
    match namespace="^quickshell-wallpaper$"
}

layer-rule {
    match namespace="^quickshell-overview$"
    place-within-backdrop true
}

---

Development

Project Structure

Noctalia/
├── shell.qml              # Main shell entry point
├── Modules/               # UI components
│   ├── Bar/              # Status bar components
│   ├── Dock/             # Application launcher
│   ├── SidePanel/        # Quick access panel
│   ├── SettingsPanel/    # Configuration interface
│   └── ...
├── Services/             # Backend services
│   ├── CompositorService.qml
│   ├── WorkspacesService.qml
│   ├── AudioService.qml
│   └── ...
├── Widgets/              # Reusable UI components
├── Commons/              # Shared utilities
├── Assets/               # Static assets
└── Bin/                  # Utility scripts

Contributing

1. Follow the existing code style and patterns
2. Use the modular architecture for new features
3. Implement proper error handling and logging
4. Test with both Hyprland and Niri compositors (if applicable)

Contributions are welcome! Don't worry about being perfect - every contribution helps! Whether it's fixing a small bug, adding a new feature, or improving documentation, we welcome all contributions. Feel free to open an issue to discuss ideas or ask questions before diving in. For feature requests and ideas, you can also use our discussions page.

---

💜 Credits

A heartfelt thank you to our incredible community of contributors. We are immensely grateful for your dedicated participation and the constructive feedback you've provided, which continue to shape and improve our project for everyone.

---

Acknowledgment

Special thanks to the creators of Caelestia and DankMaterialShell for their inspirational designs and clever implementation techniques.

---

Donation

While I actually didn't want to accept donations, more and more people are asking to donate so... I don't know, if you really feel like donating then I obviously highly appreciate it but PLEASE never feel forced to donate or anything. It won't change how we work on Noctalia, it's a project that we work on for fun in the end.

Thank you to everyone who supports me and this project 💜!

• Gohma
• PikaOS

---

License

This project is licensed under the terms of the MIT License.