qutebrowser Tips

I ♥︎ qutebrowser and recently set it up from scratch and wrote these notes so it will be easier for me next time. I hope these notes make it easier for you too.

What is qutebrowser?

“qutebrowser (pronounced "cute browser") is a web browser for Linux, Windows, and macOS operating systems with Vim[1]-style key bindings and a minimal GUI. It is keyboard-driven”

Tips

The first tip is specific to Windows, but the rest are relevant to all systems.

1. Installing qutebrowser on Windows

As of qutebrowser v1.7.0[2] the Windows installer gives you the option to set qutebrowser as your default browser and/or register it with Windows. To get these options, use one of the following installers, which are available on github.com/qutebrowser/qutebrowser/releases.

  • qutebrowser-version-amd64.exe — 64-bit version for x64 (also known as AMD64) systems

  • qutebrowser-version-win32.exe — 32-bit version for x86 systems

 

2. :version

After you install qutebrowser, launch it and do the following.

  1. Press the Esc[3] key to make sure you are in command mode.[4]

  2. Type :version, which is a Vim-style colon command.[5] This displays the version and a lot of other information, including the config and data directory paths. On a default Windows installation, these paths are displayed like this (with username replaced with your user name):

    config: C:\Users\username\AppData\Roaming\qutebrowser\config
    data: C:\Users\username\AppData\Roaming\qutebrowser\data

    Make note of these paths because they are used in Tips 4, 5, and 7 below.

  1. To close this (or any) tab, press d for delete.

✒︎

In qutebrowser the following are equivalent commands.

  • :version

  • open qute://version

  • o qute://version

 

3. Invoking commands

If a command does not work in qutebrowser, try the following.

  • Press Esc to make sure you are in command mode.[4] Sometimes you need to press Esc — and possibly Enter — multiple times to escape from a previous command.

  • Make sure you have entered the command correctly. A common mistake for me is to use a leading colon (:) when the command is not a colon command.[5]

  • Since qutebrowser commands are case sensitive, make sure you are using the correct case and that the CapsLock key is not on.

  • Make sure you press Enter after typing a colon command.

  • Make sure you press Enter followed by Esc after you are done searching for string with either the /string or the ?string command.

 

4. :adblock-update

If you are not opposed to using an ad blocker, I recommend that you run this colon command:

:adblock-update

This creates a file named blocked-hosts in the qutebrowser data directory (discussed in Tip 2).

If you were not able to read the message that :adblock-update briefly displayed, you can view it and all messages from this qutebrowser session with the following colon command.

:messages

After viewing the message(s), you can return to the previous page by typing H (a mnemonic to remember this command is “H for History”).

 

5. Creating config.py

There is more than one way to configure qutebrowser, which you can read about in Configuring qutebrowser. I recommend that you create a template configuration file by running this colon command:

:config-write-py --defaults

This creates a template config.py in your qutebrowser config directory (discussed in Tip 2). You can view the template config.py that qutebrowser v1.7.0 creates on Infinite Ink’s qutebrowser’s config.py.

 

6. Quitting qutebrowser

Before you edit config.py, which was created in the previous Tip, quit qutebrowser with one of these colon commands:

  • :qa  -  quit all without saving the currently open windows and tabs

  • :wqa  -  save (write) the currently open windows and tabs, and quit all

 

7. Editing config.py

In a plain text editor, open the config.py that we created in Tip 5. Read through the configuration settings and edit the ones that you would like to change. Here is an excerpt of my config.py:

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')

My last two settings above allow me to use Ctrl+= and Ctrl+- to zoom in and zoom out on a web page. With these settings, the qutebrowser zoom defaults, which are + and -, still work.

The template config.py that qutebrowser v1.7.0 creates is 1873 lines of comments and you can view it on Infinite Ink’s qutebrowser’s config.py.

See also

Infinite Ink’s #qutebrowser is a portal to the qutebrowser world.


1. Vim is a text editor that is based on the old Unix editor vi. It is pre-installed on most nix-based systems and can be run with a text-based or graphical user interface (TUI or GUI). Information about Vim is at wikipedia.org/wiki/Vim_(text_editor).
2. qutebrowser 1.7.0 was released on 2019-July-18. Details about this and other releases are at github.com/qutebrowser/qutebrowser/releases.
3. On an English US keyboard, pressing Ctrl+[ (Ctrl+left bracket) is equivalent to pressing the Esc key. This is useful if you are using a keyboard that does not have an Esc key or if you prefer to not take your fingers off the “home row” of your keyboard. More about this is at vim.fandom.com/wiki/Avoid_the_escape_key.
4. Vim and apps with Vim-style key bindings, such as qutebrowser, are modal. Usually you are in either command mode or insert mode. Command mode is also known as “normal mode.”
5. A Vim-style command that starts with a colon (:) is known as a “colon command” or “Ex command.”

Discussion and suggestions💬

In the comment form below you can use GitHub-flavored Markdown, which supports emoji shortcodes. For example, if you want to suggest a useful link, you could include the string :link: which will be rendered as 🔗️. Hundreds of emoji shortcodes are listed on this Emoji Cheat Sheet.

All comments are welcome, including relevant links to your site❣︎