qutebrowser A keyboard-driven browser.

qutebrowser's primary maintainer, The-Compiler, is currently working part-time on qutebrowser, funded by donations.

To sustain this for a long time, your help is needed! See the GitHub Sponsors page or alternative donation methods for more information. Depending on your sign-up date and how long you keep a certain level, you can get qutebrowser t-shirts, stickers and more!

Writing qutebrowser userscripts

qutebrowser is extensible by writing userscripts which can be called via the :spawn --userscript command, or via a key binding.

You can also call a userscript via hints so they get the selected hint URL by calling :hint links userscript ....

These userscripts are similar to the (non-javascript) dwb userscripts. They can be written in any language which can read environment variables and write to a FIFO. Note they are not related to Greasemonkey userscripts.

Note for simple things such as opening the current page with another browser or mpv, a simple key binding to something like :spawn mpv {url} should suffice.

Also note userscripts need to have the executable bit set (chmod +x) for qutebrowser to run them.

To call a userscript, it needs to be stored in your config or data directory under userscripts (for example: ~/.local/share/qutebrowser/userscripts/myscript), or just use an absolute path.

Note
 On Windows, only userscripts with com, bat, or exe extensions will be launched. As an additional resource, see Infinite Ink: qutebrowser Userscripts on Windows.

Getting information

The following environment variables will be set when a userscript is launched:

  • QUTE_MODE: Either hints (started via hints) or command (started via command or key binding).

  • QUTE_USER_AGENT: The currently set user agent, if customized.

  • QUTE_FIFO: The FIFO or file to write commands to.

  • QUTE_HTML: Path of a file containing the HTML source of the current page.

  • QUTE_TEXT: Path of a file containing the plaintext of the current page.

  • QUTE_CONFIG_DIR: Path of the directory containing qutebrowser’s configuration.

  • QUTE_DATA_DIR: Path of the directory containing qutebrowser’s data.

  • QUTE_DOWNLOAD_DIR: Path of the downloads directory.

  • QUTE_COMMANDLINE_TEXT: Text currently in qutebrowser’s command line. Note this is only useful for userscripts spawned (e.g. via a keybinding) when qutebrowser is still in command mode. If you want to receive arguments passed to your userscript via :spawn, use the normal way of getting commandline arguments (e.g. $@ in bash or sys.argv / argparse / … in Python).

  • QUTE_VERSION: The version of qutebrowser, as a string like "2.0.0". Note that this was added in v2.0.0, thus older versions can only be detected by the absence of this variable.

In command mode:

  • QUTE_URL: The current page URL.

  • QUTE_TITLE: The title of the current page.

  • QUTE_SELECTED_TEXT: The text currently selected on the page.

  • QUTE_COUNT: The count from the spawn command running the userscript.

  • QUTE_TAB_INDEX: The current tab’s index.

In hints mode:

  • QUTE_URL: The URL selected via hints.

  • QUTE_CURRENT_URL: The current page URL.

  • QUTE_SELECTED_TEXT: The plain text of the element selected via hints.

  • QUTE_SELECTED_HTML: The HTML of the element selected via hints.

Sending commands

Normal qutebrowser commands can be written to $QUTE_FIFO and will be executed.

On Unix/macOS, this is a named pipe and commands written to it will get executed immediately.

On Windows, this is a regular file, and the commands in it will be executed as soon as your userscript terminates. This means when writing multiple commands, you should append to the file (>> in bash) rather than overwrite it (>).

Examples

Opening the currently selected word on dict.cc:

#!/bin/bash

echo "open -t https://www.dict.cc/?s=$QUTE_SELECTED_TEXT" >> "$QUTE_FIFO"

Libraries

Some third-party libraries are available to make writing userscripts easier: