Getting Started with qutebrowser

I the qutebrowser web browser and recently set it up from scratch and wrote these tips so it will be easier for me next time. I hope they make it easier for you too.

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.

2020-May  Changed the title of this article to Getting Started with qutebrowser and created a new Infinite Ink article titled qutebrowser Tips and Fragments.

What is qutebrowser?

“qutebrowser (pronounced "cute browser") is a web browser for Linux, Windows, and macOS 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 register qutebrowser with Windows and set it as your default browser. To get these options, use one of the following installers, which are available on github.com/qutebrowser/qutebrowser/releases.

 

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 like the following (with username replaced with your user name).

    Version info
             ______     ,,
        ,.-"`      | ,-` |
      .^           ||    |
     /    ,-*^|    ||    |
    ;    /    |    ||    ;-*```^*.
    ;   ;     |    |;,-*`         \
    |   |     |  ,-*`    ,-"""\    \
    |    \   ,-"`    ,-^`|     \    |
     \    `^^    ,-;|    |     ;    |
      *;     ,-*`  ||    |     /   ;;
        `^^`` |    ||    |   ,^    /
              |    ||    `^^`    ,^
              |  _,"|        _,-"
              -*`   ****"""``
    
    qutebrowser v1.13.1
    ⋮
    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 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

 

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 the /string or the ?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 qt.args
:help :config-write-py
:help :devtools
:help :download
:help :help
:help :reload
:help :view-source
:help :yank
      👆
      notice the leading colon on most of these sample topics

 

5. :adblock-update

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 the 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 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 v1.8.1 and v1.8.2, but YMMV so backup your config.py (which is a good idea anyway😃).

 

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:

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.13.1 creates is 2131 lines and you can view it on Infinite Ink’s qutebrowser’s Template config.py.

 

9. Launching qutebrowser from a command line

If qutebrowser is on your path, you can easily launch it from a command line with arguments. For example, you can use the following to view Infinite Ink’s home page in a new qutebrowser window.

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

Possible command-line arguments are described on qutebrowser’s man page.

For more qutebrowser-related links, see Infinite Ink’s #qutebrowser Portal.

Endnotes


1. Vim is a text editor that is an improved version of the the old Unix editor vi. It is pre-installed on most nix-based systems and can be run with a graphical or text-based user interface (GUI or TUI). Information about Vim is at wikipedia.org/wiki/Vim_(text_editor).
2. qutebrowser v1.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.”
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.

Edit this page 📝

To add a comment or reaction emoji (👍 👎 😂 🎉 😕 ❤ 🚀 or 👀) to this page, you need JavaScript enabled in your browser and a GitHub account.