Getting Started With qutebrowser
Updated  by  nm  2025-January-23

Page contents

News

Ongoing  According to Repology, the newest packaged qutebrowser is version latest packaged version of qutebrowser. To keep up with qutebrowser releases, see github.com/qutebrowser/qutebrowser/releases, listi.jpberlin.de/pipermail/qutebrowser/, or old.reddit.com/r/qutebrowser/.

2019-August-10  Published this evolving⁠[1] article.

 

What is qutebrowser?

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

 

Tips

Below are some tips that are especially relevant to getting started with qutebrowser.

 

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⁠[2] key to make sure you are in normal mode.⁠[3]

  2. Type :version, which is a Vim-style colon command.⁠[4] This displays the version and a lot of other information, including the paths to the config and data directories. On a default Windows installation, this looks something like the following (with USERNAME replaced with your user name).

    Version info
         ______     ,,
    ,.-"`      | ,-` |
  .^           ||    |
 /    ,-*^|    ||    |
;    /    |    ||    ;-*```^*.
;   ;     |    |;,-*`         \
|   |     |  ,-*`    ,-"""\    \
|    \   ,-"`    ,-^`|     \    |
 \    `^^    ,-;|    |     ;    |
  *;     ,-*`  ||    |     /   ;;
    `^^`` |    ||    |   ,^    /
          |    ||    `^^`    ,^
          |  _,"|        _,-"
          -*`   ****"""``

qutebrowser v3.4.0
⋮
adblock: 0.6.0
⋮
config: C:\Users\USERNAME\AppData\Roaming\qutebrowser\config
data: C:\Users\USERNAME\AppData\Roaming\qutebrowser\data
⋮

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

  3. 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 tips 6 and 8 below.

 

3. Invoking commands

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

  • Press Esc to make sure you are in normal mode.⁠[3] 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 a command is not a colon command.⁠[4]

  • 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 (forward search) or a ?⁠string (backward search) 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 :open
: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 launch devtools with any of the following 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.⁠[5]

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”).⁠[6]

 

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.[5]

ℹ

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.5.1 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-v3.4.0.py

This and other :config-write-py arguments are described in qutebrowser.org/doc/help/​commands.html#config-write-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. Read through the default configuration settings — which are all commented out — and uncomment and edit the ones you would like to change. For example, here are some of my settings:

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

c.content.autoplay = False

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

 

💡

 

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

For more about qutebrowser, see Infinite Ink’s…

 

Endnotes

1. Many Infinite Ink pages, including this one, are evergreen 🌲 and regularly updated.
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 normal mode or insert mode. Normal mode is also known as “command mode.”
4. A Vim-style command that starts with a colon (:) is known as a “colon command” or “Ex command.”
5. To find out your qutebrowser config and data directories, run the :version command from within qutebrowser.
6. 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.

Please share & discuss 📝 👎 👍 📯