qutebrowser Tips and Fragments

Page contents

News

2020-July-17  qutebrowser v1.13.1 released. To keep up with qutebrowser releases, see github.com/qutebrowser/qutebrowser/releases, lists.schokokeks.org/pipermail/qutebrowser/, or old.reddit.com/r/qutebrowser/.

2020-June  qutebrowser started using GitHub Discussions Beta — check out this discussion group at github.com/qutebrowser/qutebrowser/discussions.

 

Prerequisites

This article assumes that you know the basics about the qutebrowser web browser. Some basics are discussed in Infinite Ink’s Getting Started with qutebrowser.

1. Editing your config.py

To get the most flexibility configuring qutebrowser, I recommend that you use a config.py file. To learn about this file and view a list of almost[1] all possible qutebrowser settings, see Infinite Ink’s qutebrowser’s Template config.py.

1.1. Using qutebrowser’s configured editor

You can edit config.py by doing the following within qutebrowser.

  1. Run the colon command :config-edit, which will open config.py in the editor specified by the c.editor.command configuration setting.

  2. Edit the file, save your edits, and quit the editor. qutebrowser will automatically source the newly edited config.py.

 

1.2. Using any editor

Alternatively, you can do the following.

  1. In a plain text editor, open config.py.[2]

  2. Edit the file.

  3. Save your edits.

  4. Within qutebrowser run the colon command :config-source.

2. Compartmentalizing your config.py

If you want to use multiple configuration files or put some of your configuration settings somewhere other than qutebrowser’s config directory,[2] you can put a line like the following in your config.py.

config.source('C:\\Users\\username\\Sync\\​qb\\config2.py')

This setting works on my Windows devices (with username replaced with my user name).

Backslash (\) escapes the next character from its special python or qutebrowser meaning. To specify an actual backslash, use \\.

 

💡
Starting with qutebrowser v1.9.0, I experienced a lot of crashes in qutebrowser on Windows. After I moved all my config.py lines (other than the above config.source line) to my Sync directory, these crashes stopped. If you are experiencing qutebrowser crashes, you may want to try doing something like this. Some info about this is in the qutebrowser GitHub repository in Service Worker related crashes on Windows · Issue #5634.

 

3. About key bindings

If you create a key binding, you may want to start it with a comma (,) because @The-Compiler (Florian Bruhin), qutebrowser’s main developer, has said that no default key binding will ever start with a comma.

To view all key bindings, run the following from within qutebrowser.

:bind

This lists both built-in and user-defined key bindings.

💡
If you start all your user-defined key bindings with comma (,), then typing , in normal mode (also known as command mode) will pop up a list of your user-defined bindings. This is useful if you don’t remember all your bindings.🤔

4. Some of my settings

Here are some of my config.py settings. Note that a line that begins with a hash (#) is a comment and is ignored by qutebrowser.

The highlighted lines below are useful for editing config.py, which is discussed in 1. Editing config.py above.

c.content.default_encoding = 'utf-8'

c.content.geolocation = False

c.scrolling.bar = 'always'

c.tabs.background = True

c.zoom.default = '150%'

config.bind('<Ctrl-=>', 'zoom-in')

config.bind('<Ctrl-->', 'zoom-out')

## Next works on my Windows devices
c.editor.command = ['code.cmd', '-n', '{file}', '-w']

## Next works on my Windows devices (but is commented out for now)
# c.editor.command = ['gvim.bat', '-f', '{file}', '-c', 'normal {line}G{column0}l']

## I like my start page(s) and default page to be blank
c.url.start_pages = ["about:blank"]
c.url.default_page = "about:blank"

## I like to save web pages in MHTML format
## Thanks to the next key binding, I can use ,sm to do that
config.bind(',sm', 'set-cmd-text :download --mhtml')

## Next works on my Windows devices
c.downloads.location.directory = '%USERPROFILE%\\Downloads\\MHTML\\'

c.downloads.location.suggestion = 'both'

## ,ya is my shortcut to “yank asciidoc-formatted link”
config.bind(',ya', 'yank inline {url}[{title}]')

## ,ym is my shortcut to “yank markdown-formatted link”
## ym (without a leading comma) also works because it is built-in
config.bind(',ym', 'yank inline [{title}]({url})')

## next is a note to self about how to bind JavaScript code to a key shortcut
# config.bind(',hw', "jseval alert('Hello World')")

 

When specifying commands — such as the highlighted c.editor.command settings above — you must specify the full executable name, including the file extension if there is one.

 

5. Variables

Variables can be used in the arguments of a qutebrowser command. Here is an excerpt from qutebrowser.org/doc/help/commands.html:

  • {url} expands to the URL of the current page

  • {url:pretty} expands to the URL in decoded format

  • {url:host}, {url:domain}, {url:auth}, {url:scheme}, {url:username}, {url:password}, {url:host}, {url:port}, {url:path} and {url:query} expand to the respective parts of the current URL

  • {title} expands to the current page’s title

  • {clipboard} expands to the clipboard contents

  • {primary} expands to the primary selection contents

 

💡

To see the difference between {url} and {url:pretty}, use the commands yy and yp while viewing a page whose URL contains a non-ASCII character, for example:

To view what was yanked by yy and yp, use qutebrowser’s :messages command.

 

6. JavaScript and the t[Ss][Hh] commands

qutebrowser’s default is:

c.content.javascript.enabled = True

If you want to surf the web without JavaScript, put the following in your config.py:

c.content.javascript.enabled = False

If you go to a website that you trust and want to turn on JavaScript, run the following command in qutebrowser:

tsh

This means toggle scripting for the current host during the current qutebrowser session. If you want to make this permanent for this host, use capital letter S, i.e.:

tSh

If you want to include subdomains of the current host, use capital letter H, i.e., one of the following.

tsH
tSH
t means toggle so if JavaScript is True, a t[Ss][Hh] command will change it to False.

7. autoconfig.yml

If you use tSh or tSH to permanently allow JavaScript on a host, this permanence is stored in a file named autoconfig.yml in your qutebrowser config directory. The next qutebrowser session will not know about autoconfig.yml settings unless the following line is in your config.py.

config.load_autoconfig()

 

8. Calling a WSL bash script from a Windows userscript🔨

I’d rather write a bash shell script than a Windows batch file and, thanks to WSL (Windows Subsystem for Linux), most of my Windows qutebrowser scripting is actually bash scripting. In this section, I briefly describe my tumblelog.cmd batch file userscript and my tumblelog.sh bash script that it calls.

To learn about qutebrowser userscripts, see:

 

8.1. Key binding in config.py

I put the following line in my config.py.

config.bind(',t', 'spawn --userscript tumblelog.cmd')

This makes it possible to use ,t to launch my tumblelog.cmd batch file userscript, which will add qutebrowser’s current web page to Infinite Ink’s #tumblelog Portal.

 

8.2. tumblelog.cmd batch file

In the Windows file system, my qutebrowser data directory[2] contains userscripts\tumblelog.cmd, which comprises the following five lines.

@REM change code page so UTF-8 characters work
chcp 65001

@REM pass six QUTE_ variables to the bash script
wsl.exe /home/wslusername/Scripts/tumblelog.sh "%QUTE_URL%" "%QUTE_TITLE%" "%QUTE_SELECTED_TEXT%" "%QUTE_COMMANDLINE_TEXT%" "%QUTE_HTML%" "%QUTE_TEXT%"

 

  • wslusername is my WSL username.

  • This tumblelog.cmd batch file does not work if any tumblelog.sh argument, for example %QUTE_TITLE%, contains a non-smart double quotation mark (").⁠[3]

 

8.3. tumblelog.sh bash script

In the WSL file system, my ~/Scripts/tumblelog.sh starts out like this:

#!/bin/bash

QURL=$1
QTITLE=$2
QSELECTED=$3
QCOMMANDLINE=$4
QHTMLPATH=`wslpath $5`
QTEXTPATH=`wslpath $6`

# below here, I use a heredoc to create a Hugo leaf bundle

Someday I will publish the rest of my tumblelog.sh script, but for now I hope this is enough to get you started using WSL bash scripts with qutebrowser.

 

8.4. Caveats

  • I am using WSL 1 (not WSL 2).

  • It is likely that there is a better way to use bash scripts with qutebrowser on Windows (maybe with WSLENV or the WSL bash command mentioned in How can I access WIN system variables in WSL). If you have thoughts about this, please post them below!

9. Displaying all your non-default settings

Within qutebrowser, you can display all your non-default config.py and autoconfig.yml settings with any of the following equivalent commands.

:config-diff
:open qute://configdiff
o qute://configdiff

Also see Infinite Ink’s #qutebrowser Portal, which includes qutebrowser-related links from around the web.

Endnotes


1. qutebrowser’s template config.py does not include the config.source configuration setting, which is discussed above in 2. Compartmentalizing your config.py.
2. To find out your qutebrowser config and data directories run the :version command from within qutebrowser.
3. A non-smart quotation mark is also known as a dumb, neutral, vertical, straight, typewriter, or ASCII quotation mark.

Edit this page 📝👍👎

To add a comment or reaction emoji to this page, you need a GitHub account.