Getting Started with qutebrowser
Updated 2021-June-15

Page contents

News

2021-June-6  Expanded this article’s tip about Installing qutebrowser on Windows and moved it to its own page. Check it out at www.ii.com/installing-qutebrowser-on-windows/.

2021-June-1  qutebrowser v2.2.3 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-August-10  As of today, this evolving⁠[1] article has been on the web for one year.🎂

What is qutebrowser?

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

Tips

1. Installing qutebrowser

To learn how to install qutebrowser…

 

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, this looks something like the following (with USERNAME replaced with your user name).

    Version info
             ______     ,,
        ,.-"`      | ,-` |
      .^           ||    |
     /    ,-*^|    ||    |
    ;    /    |    ||    ;-*```^*.
    ;   ;     |    |;,-*`         \
    |   |     |  ,-*`    ,-"""\    \
    |    \   ,-"`    ,-^`|     \    |
     \    `^^    ,-;|    |     ;    |
      *;     ,-*`  ||    |     /   ;;
        `^^`` |    ||    |   ,^    /
              |    ||    `^^`    ,^
              |  _,"|        _,-"
              -*`   ****"""``
    
    qutebrowser v2.2.3
    ⋮
    adblock: 0.4.4
    ⋮
    config: C:\Users\USERNAME\AppData\Roaming\qutebrowser\config
    data: C:\Users\USERNAME\AppData\Roaming\qutebrowser\data
    ⋮

    Make note of the config and data paths because they are used in tips 5, 6, and 8 below.

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

💡

In qutebrowser the following are equivalent.

  • :version

  • :open qute://version

  • o qute://version

Note that o is one of qutebrowser’s default key bindings. It is specified via config.bind('o', 'set-cmd-text -s :open') in qutebrowser’s default config.py, which is discussed in tip 6 below.

 

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 a 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 CapsLock 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 a /string or ?string command.

 

4. Getting help

To get help about qutebrowser commands, see:

A lot of help documents, including the above three, are built in to qutebrowser. To access qutebrowser’s built-in help, use any of the following within qutebrowser.

  • :help

  • :open qute://help

  • o qute://help

To get help about a specific topic, use :help topic, for example:

:help bindings.default
:help content.blocking.method    # new in v2.0.0
:help qt.args
:help :config-write-py
:help :download
:help :help
:help :reload
:help :view-source
:help :yank
:help :devtools
      👆
     notice the leading colon on most of these example topics

 

💡

In qutebrowser’s documentation and discussion groups, devtools, which is the last example above, is sometimes called “web inspector” or “inspector.” You can invoke devtools with any of the following four commands.

  • wi (which is equivalent to :devtools)

  • wIw (which is equivalent to :devtools window)

To learn more about this, run :help :devtools within qutebrowser or see qutebrowser.org/doc/help/commands.html#devtools.

 

5. Hosts blocking with :adblock-update

In qutebrowser v2.0.0 and newer, you have the option to use hosts blocking and/or Brave’s Adblock Plus (ABP). This section is about setting up hosts blocking, which is available in all versions of qutebrowser.

If you are not opposed to using an ad blocker, I recommend that you run the following colon command.

:adblock-update

This creates or updates a file named blocked-hosts in your qutebrowser data directory.⁠[6]

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 one of the following (essentially equivalent) colon commands.

:messages
:messages --plain

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

 

6. Creating config.py

There is more than one way to configure qutebrowser, which you can read about in qutebrowser.org’s Configuring qutebrowser. I recommend that you create a template configuration file by running the following colon command from within quitebrowser.

:config-write-py --defaults

This creates a file named config.py in your qutebrowser config directory.[6]

If config.py already exists, qutebrowser will not overwrite it. Instead it will display a message similar to this:

/full/path/to/config.py already exists - use --force to overwrite!

I tested this with qutebrowser v2.1.0 and some other versions but YMMV so backup your config.py (which is a good idea anyway⁠😃).

 

💡

You can specify an alternate output filename with a command like this:

:config-write-py --defaults config-v2.2.3-defaults.py

 

More about the config.py file is in Tip 8 below.

 

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

 

8. Editing config.py

In a plain text editor, open the config.py that we created in Tip 6 above. Read through the default configuration settings — which are all commented out — and uncomment and edit the ones that you would like to change. For example, here are some of my settings:

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

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

 

Note that…

  • A line that begins with a hash (#) is a comment and is ignored by qutebrowser.

  • The two config.bind 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 v2.2.3 creates is 2358 lines and you can view it on Infinite Ink’s qutebrowser’s Template config.py.

 

9. Running qutebrowser from a command line

If qutebrowser is on your path, you can easily run it from a command-line prompt.

 

Example 1

To view Infinite Ink’s home page in a private qutebrowser window, use this command:

qutebrowser 'https://www.ii.com/' --target private-window

 

Example 2

To write out qutebrowser’s default configuration settings to filename.py, use a command like this:

qutebrowser ':config-write-py --defaults filename.py'

 

Example 3

To launch qutebrowser without your config, data, etc. files, use either of these:

qutebrowser --temp-basedir
qutebrowser -T

These equivalent commands are useful for debugging.

 

💡
To view all possible command-line arguments, see qutebrowser’s man page.

 

See also

Endnotes


1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.
2. Vim is a text editor that is an improved version of the the old Unix editor vi. It is pre-installed on most Unix-like systems and can be run with a graphical or text-based user interface (GUI or TUI). For an overview, see wikipedia.org/wiki/Vim_(text_editor).
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.”
6. To find out your qutebrowser config and data directories, run the :version command from within qutebrowser.
7. In qutebrowser, upper-case H, J, K, and L mean back, tab-next, tab-prev, and forward. This is similar to how lower-case h, j, k, and l mean left, down, up, and right in qutebrowser and almost all apps with Vim-style key bindings.

Comments 👍 👎 📝

Please comment so I know (maybe) that I'm not all alone in an infinite void.