qutebrowser/doc/FAQ.asciidoc

Frequently asked questions
==========================
The Compiler <mail@qutebrowser.org>

[qanda]
What is qutebrowser based on?::
    qutebrowser uses http://www.python.org/[Python], http://qt-project.org/[Qt]
    and http://www.riverbankcomputing.com/software/pyqt/intro[PyQt].
+
The concept of it is largely inspired by http://portix.bitbucket.org/dwb/[dwb]
and http://www.vimperator.org/vimperator[Vimperator]. Many actions and
keybindings are similar to dwb.

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
    link:http://qt-project.org/[Qt]/link:http://www.riverbankcomputing.com/software/pyqt/intro[PyQt].
+
Read the next few questions to find out why I was unhappy with existing
software.

What's wrong with link:http://portix.bitbucket.org/dwb/[dwb]/link:http://sourceforge.net/projects/vimprobable/[vimprobable]/link:https://mason-larobina.github.io/luakit/[luakit]/link:http://pwmt.org/projects/jumanji/[jumanji]/... (projects based on WebKitGTK)?::
    Most of them are based on the http://webkitgtk.org/[WebKitGTK+]
    http://webkitgtk.org/reference/webkitgtk/stable/index.html[WebKit1] API,
    which causes a lot of crashes. As the GTK API using WebKit1 is
    https://lists.webkit.org/pipermail/webkit-gtk/2014-March/001821.html[deprecated],
    these bugs are never going to be fixed.
+
The newer http://webkitgtk.org/reference/webkit2gtk/stable/index.html[WebKit2
API] seems to lack basic features like proxy support, and almost no projects
seem to have started porting to WebKit2 (I only know of
http://www.uzbl.org/[uzbl]).
+
qutebrowser uses http://qt-project.org/[Qt] and
http://qt-project.org/wiki/QtWebKit[QtWebKit] instead, which suffers from far
less such crashes. It might switch to
http://qt-project.org/wiki/QtWebEngine[QtWebEngine] in the future, which is
based on Google's https://en.wikipedia.org/wiki/Blink_(layout_engine)[Blink]
rendering engine.

What's wrong with https://www.mozilla.org/en-US/firefox/new/[Firefox] and link:http://5digits.org/pentadactyl/[Pentadactyl]/link:http://www.vimperator.org/vimperator[Vimperator]?::
    Firefox likes to break compatibility with addons on each upgrade, gets
    slower and more bloated with every upgrade, and has some
    https://blog.mozilla.org/advancingcontent/2014/02/11/publisher-transformation-with-users-at-the-center/[horrible
    ideas] lately.
+
Also, developing addons for it is a nightmare.

What's wrong with http://www.chromium.org/Home[Chromium] and https://vimium.github.io/[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.

Why Python?::
    I enjoy writing Python since 2011, which made it one of the possible
    choices. I wanted to use http://qt-project.org/[Qt] because of
    http://qt-project.org/wiki/QtWebKit[QtWebKit] so I didn't have
    http://qt-project.org/wiki/Category:LanguageBindings[many other choices]. I
    don't like C++ and can't write it very well, so that wasn't an alternative.

But isn't Python too slow for a browser?::
    http://www.infoworld.com/d/application-development/van-rossum-python-not-too-slow-188715[No.]
    I believe efficency while coding is a lot more important than efficency
    while running. Also, most of the heavy lifting of qutebrowser is done by Qt
    and WebKit in C++, with the
    https://wiki.python.org/moin/GlobalInterpreterLock[GIL] released.

Is there an adblocker?::
    There is a host-based adblocker which takes /etc/hosts-like lists. A "real"
    adblocker has a
    http://www.reddit.com/r/programming/comments/25j41u/adblock_pluss_effect_on_firefoxs_memory_usage/chhpomw[big
    impact] on browsing speed and
    https://blog.mozilla.org/nnethercote/2014/05/14/adblock-pluss-effect-on-firefoxs-memory-usage/[RAM
    usage], so implementing it properly might take some time and won't be done
    for v0.1 if at all.

== Troubleshooting

Configuration not saved after modifying config.::
    When editing your config file manually, qutebrowser must be exited completely.
    Either by issuing the command `:quit` or by pressing `ctrl+q`.

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 allow-plugins true`
    in qutebrowser will enable plugins. Packages for flash should
    be provided for your platform. Read any help documentation with regards to
    installing flash from your operating systems.  Flash can also be
    obtained from http://get.adobe.com/flashplayer/[Adobe].
    This can also be set manually in your config file located in
    `~/.config/qutebrowser/qutebrowser.conf` on *nix systems. Before editing be
    sure to exit completely. Locate the line `allow-plugins = false` and change
    to `allow-plugins = true` save the file and load your browser and enjoy flash!

Experiencing freezing on sites like duckduckgo and youtube.::
    When visiting some pages and you experience freezing and you are unable to close or
    exit the browser. In some cases this can be solved by disabling plugins, or checking if you have
    a package installed called mozplugger on your system. On Archlinux
    and Debian/Ubuntu systems the package is called mozplugger. After removing the
    package, you may need to also delete a few files in your home plugin dir. They are
    named `~/.mozilla/plugins/mozplugger*.so`. Be sure to exit the browser completely before
    removing any plugins manually. See https://github.com/The-Compiler/qutebrowser/issues/357[Issue #357]
    for more details.

Experiencing segfaults (crashes) on Debian systems.::
    For Debian it's necessary to install the `gstreamer0.10-plugins-base` package.
    This is a workaround for a bug in Qt, it has been fixed upstream in Qt 5.4
    More details can be found
    https://bugs.webkit.org/show_bug.cgi?id=119951[here].

Segfaults on Facebook, Medium, Amazon.::
    If you are on a Debian or Ubuntu based system, you might experience some crashes
    visting these sites. It's caused by a known bug in Qt. But resolved in Qt 5.4. However
    Debian and Ubuntu are slow to adopt or upgrade some packages. There is currently no
    way at this time to manually upgrade to Qt 5.4 without issue.

My issue is not listed.::
    If you experience any segfaults or crashes, you can report the issue on
    https://github.com/The-Compiler/qutebrowser/issues[qutebrowser issues].
    Be sure to read over how to create a stacktrace to report crashes of unknown cause
    by visiting https://github.com/The-Compiler/qutebrowser/blob/master/doc/stacktrace.asciidoc[reporting segfaults].

// We link to github rather than to the file here so it also works with the
// qutebrowser :help because that doesn't render HACKING.