qutebrowser A keyboard-driven browser.

Frequently asked questions

  1. What is qutebrowser based on?

    qutebrowser uses Python, Qt and PyQt.

    The concept of it is largely inspired by dwb and Vimperator. Many actions and key bindings are similar to dwb.

  2. Why another browser?

    It might be hard to believe, but I didn’t find any browser which I was happy with, so I started to write my own. Also, I needed a project to get into writing GUI applications with Python and Qt/PyQt.

    Read the next few questions to find out why I was unhappy with existing software.

  3. What’s wrong with dwb/vimprobable/luakit/jumanji/… (projects based on WebKitGTK)?

    Most of them are based on the WebKitGTK+ WebKit1 API, which causes a lot of crashes. As the GTK API using WebKit1 is deprecated, these bugs are never going to be fixed.

    When qutebrowser was created, the newer WebKit2 API lacked basic features like proxy support, and almost no projects have started porting to WebKit2. In the meantime, this situation has improved a bit, but there are stil only a few project which have some kind of WebKit2 support (see the list of alternatives).

    qutebrowser uses Qt and QtWebEngine by default (and supports QtWebKit optionally). QtWebEngine is based on Google’s Chromium. With an up-to-date Qt, it has much more man-power behind it than WebKitGTK+ has, and thus supports more modern web features - it’s also arguably more secure.

  4. What’s wrong with Firefox and Pentadactyl/Vimperator?

    Firefox likes to break compatibility with addons on each upgrade, gets slower and more bloated with every upgrade, and has some horrible ideas lately.

    Also, developing addons for it is a nightmare.

  5. What’s wrong with Chromium and Vimium?

    The Chrome plugin API doesn’t seem to allow much freedom for plugin writers, which results in Vimium not really having all the features you’d expect from a proper minimal, vim-like browser.

  6. Why Python?

    I enjoy writing Python since 2011, which made it one of the possible choices. I wanted to use Qt because of QtWebKit so I didn’t have many other choices. I don’t like C++ and can’t write it very well, so that wasn’t an alternative.

  7. But isn’t Python too slow for a browser?

    No. I believe efficiency while coding is a lot more important than efficiency while running. Also, most of the heavy lifting of qutebrowser is done by Qt and WebKit in C++, with the GIL released.

  8. Is there an adblocker?

    There is a host-based adblocker which takes /etc/hosts-like lists. A "real" adblocker has a big impact on browsing speed and RAM usage, so implementing support for AdBlockPlus-like lists is currently not a priority.

  9. How do I play Youtube videos with mpv?

    You can easily add a key binding to play youtube videos inside a real video player - optionally even with hinting for links:

    :bind m spawn mpv {url}
    :bind M hint links spawn mpv {hint-url}

    Note that you might need an additional package (e.g. youtube-dl on Archlinux) to play web videos with mpv.

    There is a very useful script for mpv, which emulates "unique application" functionality. This way you can add links to the mpv playlist instead of playing them all at once.

    It also works nicely with rapid hints:

    :bind m spawn umpv {url}
    :bind M hint links spawn umpv {hint-url}
    :bind ;M hint --rapid links spawn umpv {hint-url}
  10. How do I use qutebrowser with mutt?

    Due to a Qt limitation, local files without .html extensions are "downloaded" instead of displayed, see #566. You can work around this by using this in your mailcap:

        text/html; mv %s %s.html && qutebrowser %s.html >/dev/null 2>/dev/null; needsterminal;
  11. What is the difference between bookmarks and quickmarks?

    Bookmarks will always use the title of the website as their name, but with quickmarks you can set your own title.

    For example, if you bookmark multiple food recipe websites and use :open, you have to type the title or address of the website.

    When using quickmark, you can give them all names, like foodrecipes1, foodrecipes2 and so on. When you type :open foodrecipes, you will see a list of all the food recipe sites, without having to remember the exact website title or address.

  12. How do I use spell checking?

    Configuring spell checking in qutebrowser depends on the backend in use (see #700 for a more detailed discussion).

    For QtWebKit:

    1. Install qtwebkit-plugins.

    2. Note: with QtWebKit reloaded you may experience some issues. See #10.

    3. The dictionary to use is taken from the DICTIONARY environment variable. The default is en_US. For example to use Dutch spell check set DICTIONARY to nl_NL; you can’t use multiple dictionaries or change them at runtime at the moment. (also see the README file for qtwebkit-plugins).

    4. Remember to install the hunspell dictionaries if you don’t have them already (most distros should have packages for this).

    For QtWebEngine:

    1. Make sure your versions of PyQt and Qt are 5.8 or higher.

    2. Use dictcli.py script to install dictionaries. Run the script with -h for the parameter description.

    3. Set spellcheck.languages to the desired list of languages, e.g.: :set spellcheck.languages "['en-US', 'pl-PL']"

  13. How do I use Tor with qutebrowser?

    Start tor on your machine, and do :set content.proxy socks://localhost:9050/ in qutebrowser. Note this won’t give you the same amount of fingerprinting protection that the Tor Browser does, but it’s useful to be able to access .onion sites.

  14. Why does J move to the next (right) tab, and K to the previous (left) one?

    One reason is because dwb did it that way, and qutebrowser’s keybindings are designed to be compatible with dwb’s. The rationale behind it is that J is "down" in vim, and K is "up", which corresponds nicely to "next"/"previous". It also makes much more sense with vertical tabs (e.g. :set tabs.position left).

  15. What’s the difference between insert and passthrough mode?

    They are quite similar, but insert mode has some bindings (like Ctrl-e to open an editor) while passthrough mode only has escape bound. It might also be useful to rebind escape to something else in passthrough mode only, to be able to send an escape keypress to the website.

  16. Why takes it longer to open an URL in qutebrowser than in chromium?

    When opening an URL in an existing instance the normal qutebrowser Python script is started and a few PyQt libraries need to be loaded until it is detected that there is an instance running where the URL is then passed to. This takes some time. One workaround is to use this script and place it in your $PATH with the name "qutebrowser". This script passes the URL via an unix socket to qutebrowser (if its running already) using socat which is much faster and starts a new qutebrowser if it is not running already. Also check if you want to use webengine as backend in line 17 and change it to your needs.


Unable to view flash content.

If you have flash installed for on your system, it’s necessary to enable plugins to use the flash plugin. Using the command :set content.plugins true in qutebrowser will enable plugins. Packages for flash should be provided for your platform or it can be obtained from Adobe.

Experiencing freezing on sites like duckduckgo and youtube.

This issue could be caused by stale plugin files installed by mozplugger if mozplugger was subsequently removed. Try exiting qutebrowser and removing ~/.mozilla/plugins/mozplugger*.so. See Issue #357 for more details.

When using QtWebEngine, qutebrowser reports "Render Process Crashed" and the console prints a traceback on Gentoo Linux or another Source-Based Distro

As stated in GCC’s Website GCC 6 has introduced some optimizations that could break non-conforming codebases, like QtWebEngine.
As a workaround, you can disable the nullpointer check optimization by adding the -fno-delete-null-pointer-checks flag while compiling.
On gentoo, you just need to add it into your make.conf, like this:

CFLAGS="... -fno-delete-null-pointer-checks"
CXXFLAGS="... -fno-delete-null-pointer-checks"

And then re-emerging qtwebengine with:

emerge -1 qtwebengine
My issue is not listed.

If you experience any segfaults or crashes, you can report the issue in the issue tracker or using the :report command. If you are reporting a segfault, make sure you read the guide on how to report them with all needed information.