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: Eitherhints(started via hints) orcommand(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 orsys.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: Thecountfrom the spawn command running the userscript.
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:
-
Python: python-qutescript
-
Node.js: qutejs