qutebrowser Tips

I ❤︎ qutebrowser and recently set up version 1.7.0 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”

qutebrowser is free/libre open source software (FLOSS) and you can learn about it at qutebrowser.org.


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

1. Windows installation tip

As of qutebrowser v1.7.0, 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 Windows installers on github.com/qutebrowser/qutebrowser/releases.

  64-bit: qutebrowser-version-amd64.exe
  32-bit: qutebrowser-version-win32.exe

2. :version

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

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

  2. Type :version, which is a Vim-style colon command.[4]

    This displays the version, the paths to the config and data directories, and a lot of other information. Note the paths to the config and data directories because we use these below.

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


If a command does not work in qutebrowser, press Esc to make sure you are in command mode.[3] Sometimes you need to press the Escape key two or more times to escape from a nested command situation.😱

3. :adblock-update

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


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

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


After viewing the message(s), you can return to the previous page by typing H (for History).

4. Create 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 config.py in your qutebrowser config directory (discussed in Tip #2 above).

5. Edit config.py

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

  • :q - quit without saving the current tabs

  • :wq - save (write) the current tabs and quit

In a plain text editor, open config.py, which is in your qutebrowser config directory (discussed in Tip #2 above).

Read through the configuration settings and edit the ones you would like to change.

Here are some of my qutebrowser settings:

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

config.bind('ya', 'yank inline {url}[{title}]')

Note that in config.py, a line that begins with a hash (#) is a comment and is ignored by qutebrowser.

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 character or graphical user interface (CUI or GUI). Information about Vim is at en.wikipedia.org/wiki/Vim_(text_editor).
2. 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.
3. 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.”
4. Vim-style colon commands start with a colon (:) and are also known as “Ex commands.”