ii.com: Getting Started with qutebrowser

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

Tips

1. Installing qutebrowser

To learn how to install qutebrowser…

on Windows, see www.ii.com/installing-qutebrowser-on-windows/
on various platforms, see qutebrowser.org/doc/install.html

2. :version

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

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

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.

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.

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.

Getting Started with qutebrowser
Updated 2021-June-15