FAQ

Find answers to common questions about Noctalia installation, configuration, and usage.

Installation & Compatibility

How can I run Noctalia on distributions other than Arch and NixOS?

Most distributions offer quickshell. If you can install either, you can use Noctalia. If your distro doesn’t provide Quickshell, you can build it from source.

What window managers does Noctalia support?

Noctalia is designed for and tested with niri, Hyprland, Sway and MangoWC. While it may work with other compositors, we currently only support workspace indicators for Niri and Hyprland.

Configuration

Why are some of my app icons missing?

The issue is most likely that your environment variables and icons theme are not set properly.

Add these variables via your compositor or to /etc/environment and reboot. On NixOS, use environment.variables or home.sessionVariables.

Then use one of the three following options:

Option 1: if you prefer GTK

Set QT_QPA_PLATFORMTHEME=gtk3
Then use an utility like nwg-look (available in most distros) to select and apply your favorite icons theme.

Option 2: If you prefer Qt

Set QT_QPA_PLATFORMTHEME=qt6ct
Then run qt6ct to select and apply your favorite icons theme.

Option 3: Force an icon theme for Quickshell

Set QS_ICON_THEME="youricontheme"

For Niri users

Ensure that you set environment variables properly.

If you prefer to set these in Niri’s config

Ensure that you also launch Noctalia via Niri:

spawn-at-startup "qs" "-c" "noctalia-shell"

This is because Niri only overrides environment variables for processes it spawns.

If you prefer systemd

You can edit the noctalia.service.

1. Edit the user service configuration:

systemctl edit --user noctalia.service

2. Add variables in the [Service] section:

[Service]
Environment="QT_QPA_PLATFORM=wayland;xcb"
Environment="QT_QPA_PLATFORMTHEME=qt6ct"
Environment="QT_AUTO_SCREEN_SCALE_FACTOR=1"

3. Reload and restart the service:

systemctl --user daemon-reload
systemctl --user restart noctalia.service

How can I make the UI bigger?

First things first, you should increase your compositor scaling per monitor. This is the best solution and should give you a nice scaled up UI on HiDPI monitors.

Last Resort

You can start noctalia-shell with a special environment variable, but this is not recommended on multi-monitor setups as it will likely break tooltips and other contextual menu positioning on monitors that don’t have a (0,0) origin.

QT_SCALE_FACTOR=2 qs -c noctalia-shell

This can also be added to your compositor autostart.

How can I get Noctalia to display in my language?

Noctalia automatically uses your operating system’s language settings. If the application appears in English, it’s likely because a translation for your language isn’t available yet, causing it to use English as a fallback.

How to Change the Language Changing Noctalia’s language involves adjusting your computer’s system-wide language settings, not a setting within the app itself.

1. Check if Your Language is Supported First, you can see which translations are included with Noctalia. Look inside the installation folder for a directory named /Assets/Translations. You’ll find files ending in .json, named with language codes (e.g., es.json for Spanish, fr.json for French, de.json for German). If you don’t see a file for your language, you’ll need to use one that is available.

2. Set Your System Language You’ll need to change the primary language for your entire operating system.

The method varies by distribution. For command-line users, the localectl command is common. For example, to set your language to Spanish (Spain), you would run:

sudo localectl set-locale LANG=es_ES.UTF-8

After changing your system’s language, restart Noctalia for the changes to take effect.

If Noctalia doesn’t support your language yet, consider contributing a translation! Check the project’s repository on GitHub for instructions on how to contribute.

How do I enable fingerprint authentication on the lockscreen?

Noctalia supports fingerprint authentication via PAM. To enable it:

1. Edit the PAM configuration file at ~/.config/noctalia/pam/password.conf
2. Uncomment the fingerprint line by removing the #:

   auth sufficient pam_fprintd.so max-tries=1
   auth required pam_unix.so

3. Install required packages: fprintd and pam_fprintd
4. Enroll your fingerprint (if needed): fprintd-enroll
5. Restart Noctalia for changes to take effect

After enabling, you can unlock using either your fingerprint or password. The fingerprint will be attempted first (max 1 try), then it falls back to password authentication.

Note: The PAM configuration file is created automatically on first launch. If it doesn’t exist, restart Noctalia and it will be generated.

Window Manager Integration

How can I make empty or unused workspaces always show up in Hyprland?

To make workspaces always visible, even when empty, you need to set them as persistent in your hyprland.conf file. You can find the specific syntax and examples in the official documentation for Workspace Rules.

workspace = 1, monitor:DP-1, persistent:true
workspace = 2, monitor:DP-1, persistent:true
workspace = 3, monitor:DP-1, persistent:true
workspace = 4, monitor:DP-1, persistent:true
workspace = 5, monitor:DP-1, persistent:true

Troubleshooting

Why aren’t my keybinds working?

Common causes:

1. Wrong command syntax: Make sure you’re using the correct IPC command format
2. Window manager configuration: Verify your keybind syntax matches your WM (Hyprland vs Niri)
3. Noctalia not running: Keybinds only work when Noctalia is running

Why won’t some applications appear in the launcher?

The launcher looks for .desktop files in standard locations. If an application doesn’t appear:

1. Refresh the launcher cache by restarting Noctalia.
2. Verify that a .desktop file exists in one of these directories:
   • /usr/share/applications/
   • ~/.local/share/applications/
   • $HOME/.nix-profile/share/applications/ (apps installed with Nix/Home Manager)
   • /etc/profiles/per-user/$USER/share/applications/ (system/user-wide Nix profiles)
3. Create a .desktop file manually for custom applications if none is provided.

Why does Noctalia crash on startup?

1. Check the error output by running Noctalia from the terminal
2. Update dependencies - outdated Quickshell versions can cause issues
3. Check system logs for additional error information

Why do I have a weird gap?

This usually means noctalia-shell is running more than once (for example, launched by both your compositor autostart and the systemd service). Multiple instances fight over layout space and leave blank gaps.

Make sure only a single instance is started:

1. Stop extra copies (kill -9 qs or reboot)
2. Pick one startup method (manual, compositor autostart, systemd, or Home Manager) and disable the others

Why can’t I unlock my lock screen??

openSUSE in particular does not provide the required /etc/pam.d/login. You must create an /etc/pam.d/login manually. Execute:

sudo tee /etc/pam.d/login <<'EOF'

And enter:

%PAM-1.0

auth       include      common-auth
account    include      common-account
password   include      common-password
session    include      common-session
EOF

Why won’t my screen recorder start recording?

Common causes:

1. Missing package: Make sure you have installed the proper package or flatpak
2. Portal crashed: Verify the status of your xdg-desktop-portal-xxx service and/or restart it. On Niri the gnome portal is recommended and can be restarted using the following command: systemctl --user restart xdg-desktop-portal-gnome.service
3. Change the video source: In Noctalia’s settings, switch the source from portal to screen. And try recording.
4. Check output in terminal: gpu-screen-recorder -w screen -f 60 -a default_output -o video.mp4

Appearance & UI

Why does the shell look different than expected?

1. Check your theme settings in the settings panel
2. Verify your display settings - scaling and resolution can affect appearance
3. Update to the latest version - UI improvements are frequently released

Why does my clipboard history preview look weird?

How to fix:

1. Open Noctalia’s Settings -> Color Scheme -> Generate templates for predefined schemes -> UI -> Check the Qt checkbox (skip this part if you have your own Qt theme).

2. Install qt5ct and qt6ct on your system, then set both Color schemes to noctalia.

3. Check >clip again to see if the theme is applied (if not try to restart noctalia or logout/login again)

Still Need Help?

If your question isn’t answered here:

• Search our documentation for more detailed guides
• Join our Discord community for real-time help and discussion
• Check GitHub issues for similar problems and solutions
• Create a new issue if you’ve found a bug or need specific help

Remember to include relevant system information and error messages when asking for help!