qutebrowser Tips and Fragments
Updated 2021-October-23

Page contents

News

2021-October-21  qutebrowser v2.4.0 released. To keep up with qutebrowser releases, see github.com/qutebrowser/qutebrowser/releases, lists.schokokeks.org/pipermail/qutebrowser/, or old.reddit.com/r/qutebrowser/.

2021-May-22  As of today, this evolving⁠[1] article has been on the web for 1 year.🎂

 

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 config.py

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

 

1.1. Via any editor

One way to edit your config.py is to do the following.

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

  2. Edit the file.

  3. Save your edits.

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

 

1.2. Via qutebrowser’s configured editor

Another way to edit your config.py is to do the following within qutebrowser.

  1. Run the colon command :config-edit. This 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.

ℹ

Examples of c.editor.command settings are…

 

 

2. Compartmentalizing your config.py with config.source

If you want to use multiple configuration files or put some of your configuration settings somewhere other than qutebrowser’s config directory,⁠[3] 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).

ℹ
 In a qutebrowser config file, backslash (\) is a metacharacter and its normal meaning is to escape the next character from its normal meaning. To specify a literal backslash, use \\.

 

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 default key binding will never 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 config.py 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 are useful for editing config.py from within qutebrowser. Doing this is discussed in 1.2. Via qutebrowser’s configured editor above.

 

## In v2.0.0+, one of the following 2 settings is REQUIRED
# config.load_autoconfig(False)
config.load_autoconfig(True)

c.content.autoplay = False

## In v2.0.0+, use next if you use Adblock Plus AND hosts blocking 
c.content.blocking.method = 'both'

c.content.default_encoding = 'utf-8'

c.content.geolocation = False

## Display PDFs within qutebrowser
c.content.pdfjs = True

c.scrolling.bar = 'always'

c.zoom.default = '150%'

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

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

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

## Next works on my Windows devices (but is commented out for now)
## Note: 'gvim.bat' works but 'gvim' does not work
# 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 Windows
c.downloads.location.directory = '%USERPROFILE%\\Downloads-2021-Q4\\'

## Next works on Windows if %YEARQUARTER% environment variable exists
# c.downloads.location.directory = '%USERPROFILE%\\Downloads-%YEARQUARTER%\\'

c.downloads.location.suggestion = 'both'

## ,ya is my shortcut to “yank asciidoc-formatted link”
config.bind(',ya', 'yank inline {url:pretty}[{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:pretty})')

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

c.content.dns_prefetch = False

 

‼

When specifying an editor command in config.py, such as in the two highlighted lines above, you may need to specify the full executable name, including any file extension (.cmd, .bat, or .whatever).

Finding out the full executable name of a command — for example gvim — depends on the shell. In PowerShell, run any of the following equivalent commands.

gcm gvim
Get-Command gvim
get-command gvim

In Bash, run:

which gvim

In CMD[4] or Bash, run:

where gvim

 

5. Variables

5.1. Environment variables

Sometimes environment variables work in a config.py file. For example, the following settings, which are in my settings in the previous section, both work.

c.downloads.location.directory = '%USERPROFILE%\\Downloads-2021-Q4\\'
c.downloads.location.directory = '%USERPROFILE%\\Downloads-%YEARQUARTER%\\'

But sometimes environment variables do not work. For example, I have been unable to figure out how to use an environment variable in either of the following config.py settings.

config.source('C:\\Users\\USERNAME\\Sync\\​qb\\config2.py')
config.bind(',t', 'spawn -u "C:\\Users\\USERNAME\\Sync\\qb\\tumblelog-wrapper.cmd"')

 

5.2. qutebrowser variables

qutebrowser 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 yank commands yy and yp while viewing a page whose URL contains a non-ASCII character, for example one of the following:

 github.com/qutebrowser/qutebrowser/issues?utf8=✓&q=

 www.ii.com/ordinary-extraordinary-markdown/#footnotes👣

To view what was yanked by yy and yp, use qutebrowser’s :messages or :messages --plain 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,⁠[5] 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 one of the following equivalent lines is in your config.py.

config.load_autoconfig(True)
config.load_autoconfig()

 

8. Calling a bash script from a Windows userscript

This section is now part of Infinite Ink’s qutebrowser Userscripts on Windows.

 

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 three equivalent commands.

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

 

10. If qutebrowser crashes

Starting with v1.9.0, sometimes — although rarely — qutebrowser crashes. Unfortunately, once a single crash happens, more crashes regularly happen. The fix for this depends on the qutebrowser version.

 

10.1. Version 2.0.0 and newer

This type of crash is not happening much, if at all, in qutebrowser v2.0.0+. If it does happen, you can put the following in your config.py.

c.qt.workarounds.remove_service_workers = True

 

10.2. Version 1.14.1 and older

In qutebrowser v1.14.1 and older, do the following.

  1. Quit qutebrowser.

  2. Rename C:\Users\USERNAME\AppData\Roaming\qutebrowser\​data\webengine\Service Worker\ to C:\Users\USERNAME\AppData\Roaming\qutebrowser\​data\webengine\Service Worker-2021-10-23-CRASH\
    (with USERNAME and 2021-10-23 replaced with my user name and the Service Worker directory’s date stamp).

  3. Restart qutebrowser.

Information about this is in:

 

See also

For more about qutebrowser, see Infinite Ink’s…

 

Endnotes

1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. qutebrowser’s template config.py does not include the config.source configuration setting, which is discussed above in 2. Compartmentalizing your config.py.
3. To find out your qutebrowser config and data directories, run the :version command from within qutebrowser.
4. CMD is also known as cmd.exe and “Command Prompt”.
5. In general, I recommend surfing the web with JavaScript turned off.

Comments and questions 📝 👍 👎 🤔

Your public comment or question might immediately improve this page or help me to (eventually) improve this page.