pywalfox

Pywalfox allows for three levels of color customization via its settings GUI:

1. Palette (Temporary)

The Palette section allows you to temporarily override colors from the Pywal palette using existing colors or a colorwheel.

Warning: Changes made here are reset when you click "Fetch Pywal colors" or run pywalfox update.

2. Palette Template (Persistent)

To make color changes permanent, you must save them as a Palette template:

1. Click "Fetch Pywal colors" or run pywalfox update.
2. Customize colors in the Palette section (Note: colors from the colorwheel cannot be used in templates).
3. Click "Load from current" in the Palette template section.
4. Click "Save palette".

3. Theme Template

The Theme template assigns colors from your Palette template to specific browser elements. You can assign colors by their names as defined in your palette template.

Because Flatpaks are sandboxed, you must use a wrapper script and grant specific permissions.

1. Create a wrapper script

Create ~/.var/app/<YOUR_APP_ID>/pywalfox-wrapper.sh:

#!/bin/sh
flatpak-spawn --host ~/.local/bin/pywalfox "$@"

Make it executable:

chmod +x ~/.var/app/<YOUR_APP_ID>/pywalfox-wrapper.sh

2. Install with custom paths

pywalfox install \
--manifest-path ~/.var/app/<YOUR_APP_ID>/.<BROWSER_DIR>/native-messaging-hosts \
--profile-path  ~/.var/app/<YOUR_APP_ID>/.<BROWSER_DIR>/

3. Update the manifest

Edit the pywalfox.json file in your browser's native-messaging-hosts folder. Update the path to point to your wrapper script using an absolute path:

{
  "name": "pywalfox",
  "description": "Automatically theme your browser using the colors generated by Pywal",
  "path": "/home/<USER>/.var/app/<YOUR_APP_ID>/pywalfox-wrapper.sh",
  "type": "stdio",
  "allowed_extensions": [ "pywalfox@frewacom.org" ]
}

4. Grant permissions

Run the following to allow the Flatpak to talk to the host:

flatpak override --user \
  --talk-name=org.freedesktop.Flatpak \
  --talk-name=org.freedesktop.portal.Flatpak \
  --system-talk-name=org.freedesktop.Flatpak \
  <YOUR_APP_ID>

To use Pywalfox, you must install both the browser add-on and the native messaging application.

1. Install the Add-on: Get the Pywalfox add-on from the Firefox Add-ons store or Thunderbird Add-ons store.
2. Install the Native Application: Install the pywalfox package via pipx (recommended) or pip:

   pipx install pywalfox

3. Configure the Browser: Run the installation command to link the native app to your browser:

   pywalfox install

4. Restart: Restart Firefox or Thunderbird.
5. Apply Colors: Generate a theme with Pywal (e.g., wal --theme gruvbox), then click the Pywalfox icon in your browser and select "Fetch Pywal colors".

Note: Firefox forks (like LibreWolf) and Flatpak installations require additional configuration steps.

If Pywalfox is not working, check the following:

• Check Logs: View the Debugging section at the bottom of the Pywalfox settings page in your browser.
• Verify Pywal: Ensure ~/.cache/wal/colors exists and contains valid colors.
• Verify Manifest Path: Ensure the path in ~/<native-messaging-hosts-folder>/pywalfox.json is a valid path.

Common Error: ExtensionError: No such native application pywalfox

This means the manifest is not installed correctly.

1. Locate the manifest at <path-to-python-site-packages>/pywalfox/assets/manifest.json.
2. Copy it to the correct native-messaging-hosts directory.
3. Update the path property in the copied manifest to point to <path-to-python-site-packages>/pywalfox/bin/main.sh (or win.bat on Windows).

Common Error: pywalfox: command not found

Pywalfox requires the pywalfox executable to be in your system PATH. Ensure you can run pywalfox from your terminal without an absolute path.