Firefox

Firefox is themed through the Pywalfox browser extension. Noctalia writes a pywal-compatible colors.json and can drive the extension either with a built-in host (post_action = "firefox-theme", community template pywalfox-beta4+) or with the legacy Python pywalfox package (community template pywalfox).

Prefer pywalfox-beta4+ when your Noctalia build includes Firefox theme support. Keep the legacy path only if you still need it; both templates write $XDG_CACHE_HOME/wal/colors.json, so enable one, not both.

Recommended: pywalfox-beta4+ (built-in host)

No separate Python package. Noctalia is the native messaging host.

Requirements

• Noctalia with the built-in firefox-theme post-action
• Community template pywalfox-beta4 or newer
• The Pywalfox extension

Setup

1. Install the Pywalfox extension from Firefox Add-ons.

2. Enable the community template in Noctalia:

   • Open Settings → Templates (community templates)
   • Open Browse Templates and enable pywalfox-beta4 (display name may look like Pywalfox (beta4))
   • Leave the legacy pywalfox template off

3. Apply a theme (change wallpaper / palette, or re-apply templates) so Noctalia writes colors.json and runs firefox-theme. That installs the user-local native messaging manifest when needed: ~/.mozilla/native-messaging-hosts/pywalfox.json → your noctalia binary.

4. Restart Firefox once after the manifest is first installed so it picks up the host.

After that, palette and dark/light mode changes should update the browser without a separate daemon package.

Multiple open Firefox profiles are supported with the built-in host: each profile runs its own native-messaging process, and theme pushes fan out to all of them. The legacy Python host only refreshes one profile at a time.

Manual helpers

noctalia firefox-theme install    # write the native messaging manifest
noctalia firefox-theme update     # push colors to all running profile hosts
noctalia firefox-theme uninstall  # remove the noctalia-owned manifest
noctalia firefox-theme --help

Migrating from the legacy Python host

1. Disable the legacy pywalfox template; enable pywalfox-beta4 (or newer) instead.
2. If ~/.mozilla/native-messaging-hosts/pywalfox.json still points at a non-Noctalia binary, remove that manifest (or uninstall the Python package’s host) — Noctalia will not overwrite a foreign host.
3. Re-apply templates (or change theme) so Noctalia can install its own manifest, then restart Firefox.

Optional cleanup: uninstall python-pywalfox when you no longer need it.

Legacy: pywalfox (Python host)

Kept for existing setups until pywalfox-beta4+ is widely available. Uses the external pywalfox CLI via the community template’s post_hook.

Setup

1. Install Pywalfox (Python):

   # Arch Linux / Manjaro
   paru -S python-pywalfox

2. Install the Pywalfox browser extension from Firefox Add-ons.

3. Enable Firefox theming in Noctalia:

   • Open Settings → Templates (community templates)
   • Open Browse Templates and enable pywalfox (display name may look like Firefox (Pywalfox))
   • Leave pywalfox-beta4 off if you stay on this path

Pywalfox syncs Noctalia’s color scheme while the Python daemon / host is running. Theme updates follow Noctalia palette changes as long as that host stays up.

Troubleshooting

• Template not listed: Community templates come from https://api.noctalia.dev/templates. Refresh / reopen Settings after the catalog publishes the entry. Offline mode blocks catalog downloads.
• Extension not connecting: Confirm the extension is enabled, the manifest exists under ~/.mozilla/native-messaging-hosts/pywalfox.json, and Firefox was restarted after install.
• Colors file updates but Firefox does not: Confirm you enabled exactly one of pywalfox-beta4+ or legacy pywalfox, and that the manifest path matches the host you intend (noctalia vs Python).
• Only one of several Firefox profiles refreshes: Expected with the legacy Python host. With pywalfox-beta4+, restart each profile once after updating Noctalia so every profile is running the new host; then theme pushes should reach all open profiles.
• Stuck on the Python host after switching to beta4: Check the path field in the manifest; remove a foreign host entry before Noctalia can install its own.