Getting Started With qutebrowser
Updated  2022-August-29

Page contents


Ongoing  According to Repology, the newest packaged qutebrowser is version latest packaged version of qutebrowser. To keep up with qutebrowser releases, see,, or

2022-August-10  As of today, this evolving⁠[1] article has been on the web for 3 years.🎂🎂🎂


What is qutebrowser?


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 v2.5.3
    adblock: 0.5.2
    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, 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 invoke 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​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.


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

There is more than one way to configure qutebrowser, which you can read about in’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 in your qutebrowser config directory.[5]

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

/full/path/to/ already exists - use --force to overwrite!

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



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

:config-write-py --defaults

This and other :config-write-py arguments are described in​commands.html#config-write-py.


More about the file is in tip 8 below.


7. Quitting qutebrowser

Before you edit, 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

In a plain text editor, open the 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 2 lines is REQUIRED
# config.load_autoconfig(False)

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 = '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 '' --target private-window


Example 2

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

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


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


1. Many Infinite Ink articles, 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
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.

Discuss or share 📝 🤔 🐘