path: root/doc/faq.asciidoc

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

[qanda]
What is qutebrowser based on?::
    qutebrowser uses https://www.python.org/[Python], https://www.qt.io/[Qt] and
    https://www.riverbankcomputing.com/software/pyqt/intro[PyQt].
+
The concept of it is largely inspired by https://bitbucket.org/portix/dwb/[dwb]
and http://www.vimperator.org/vimperator[Vimperator]. Many actions and
key bindings 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:https://www.qt.io/[Qt]/link:https://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:https://bitbucket.org/portix/dwb/[dwb]/link:https://sourceforge.net/projects/vimprobable/[vimprobable]/link:https://mason-larobina.github.io/luakit/[luakit]/jumanji/... (projects based on WebKitGTK)?::
    Most of them are based on the https://webkitgtk.org/[WebKitGTK+]
    https://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.
+
When qutebrowser was created, the newer
https://webkitgtk.org/reference/webkit2gtk/stable/index.html[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
still only a few projects which have some kind of WebKit2 support (see the
https://github.com/qutebrowser/qutebrowser#similar-projects[list of
alternatives]).
+
qutebrowser uses https://www.qt.io/[Qt] and
https://wiki.qt.io/QtWebEngine[QtWebEngine] by default (and supports
https://wiki.qt.io/QtWebKit[QtWebKit] optionally). QtWebEngine is based on
Google's https://www.chromium.org/Home[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.

What's the difference to Firefox/Chromium addons like https://github.com/tridactyl/tridactyl[Tridactyl] or https://vimium.github.io/[Vimium]?::
    The WebExtensions API doesn't seem to allow much freedom for plugin
    writers, which results in Vimium/Tridactyl not really having all the
    features you'd expect from a proper minimal, vim-like browser. Due to the
    same reason, those addons are quite inconsistent - on some pages, they
    can't run and intercept keyboard inputs correctly. Tridactyl gets around
    those limitations with various measures (such as a native messenger written
    in Python doing some work which can't be done from the addon directly), but
    there's only so much that can be done.

Why Python?::
    I enjoy writing Python since 2011, which made it one of the possible
    choices. I wanted to use https://www.qt.io/[Qt] because of
    https://wiki.qt.io/QtWebKit[QtWebKit] so I didn't have
    https://wiki.qt.io/Category:LanguageBindings[many other choices]. At that
    point, I wasn't comfortable with C++ so that wasn't an alternative.

But isn't Python too slow for a browser?::
    https://www.infoworld.com/d/application-development/van-rossum-python-not-too-slow-188715[It's generally less of a problem than one would expect.]
    Most of the heavy lifting of qutebrowser is done by Qt and
    QtWebKit/QtWebEngine in C++, with the
    https://wiki.python.org/moin/GlobalInterpreterLock[GIL] released.
+
It can be problematic in some areas, but various performance optimizations have
been carried out to problematic portions of the code.

Is qutebrowser secure?::
    Most security issues are in the backend (which handles networking,
    rendering, JavaScript, etc.) and not qutebrowser itself.
+
qutebrowser uses https://wiki.qt.io/QtWebEngine[QtWebEngine] by default.
QtWebEngine is based on Google's https://www.chromium.org/Home[Chromium]. While
Qt only updates to a new Chromium release on every minor Qt release (all ~6
months), every patch release backports security fixes from newer Chromium
versions. In other words: As long as you're using an up-to-date Qt, you should
be receiving security updates on a regular basis, without qutebrowser having to
do anything. Chromium's process isolation and
https://chromium.googlesource.com/chromium/src/+/master/docs/design/sandbox.md[sandboxing]
features are also enabled as a second line of defense.
+
https://wiki.qt.io/QtWebKit[QtWebKit] is also supported as an alternative
backend, but hasn't seen new releases
https://github.com/annulen/webkit/releases[in a while]. It also doesn't have any
process isolation or sandboxing. See
https://github.com/qutebrowser/qutebrowser/issues/4039[#4039] for more details.
+
Security issues in qutebrowser's code happen very rarely (as per September 2019,
there have been three security issues caused by qutebrowser in almost 6 years).
Those were handled appropriately
(http://seclists.org/oss-sec/2018/q3/29[example]) and fixed timely. To report
security bugs, please contact me directly at mail@qutebrowser.org, GPG ID
https://www.the-compiler.org/pubkey.asc[0x916eb0c8fd55a072].

Is there an ad blocker?::
    There is a simple host-based ad blocker that takes `/etc/hosts`-like lists. 
+
More advanced ad blockers can have a 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 support for AdBlock Plus-like lists is not a priority.
How can I get No-Script-like behavior?::
    To disable JavaScript by default:
+
----
:set content.javascript.enabled false
----
+
The basic command for enabling JavaScript for the current host is `tsh`.
This will allow JavaScript execution for the current session.
Use `S` instead of `s` to make the exception permanent.
With `H` instead of `h`, subdomains are included.
With `u` instead of `h`, only the current URL is whitelisted (not the whole host).

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}
----
+
The comma prefix is used to make sure user-defined bindings don't conflict with
the built-in ones.
+
Note that you might need an additional package (e.g.
https://www.archlinux.org/packages/community/any/youtube-dl/[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.
+
You can find the script here: https://github.com/mpv-player/mpv/blob/master/TOOLS/umpv
+
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}
----

How do I use qutebrowser with mutt?::
    For security reasons, local files without `.html` extensions aren't
    rendered as HTML, see
    https://bugs.chromium.org/p/chromium/issues/detail?id=777737[this Chromium issue]
    for details. You can do this in your `mailcap` file to get a proper
    extension:
+
----
    text/html; qutebrowser %s; needsterminal; nametemplate=%s.html
----

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.

How do I use spell checking?::
	Configuring spell checking in qutebrowser depends on the backend in use
    (see https://github.com/qutebrowser/qutebrowser/issues/700[#700] for
	a more detailed discussion).
+
For QtWebKit:

. Install https://github.com/QupZilla/qtwebkit-plugins[qtwebkit-plugins].
  . Note: with QtWebKit reloaded you may experience some issues. See
    https://github.com/QupZilla/qtwebkit-plugins/issues/10[#10].
. 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`).
. Remember to install the hunspell dictionaries if you don't have them already
  (most distros should have packages for this).

+
For QtWebEngine:

. Make sure your versions of PyQt and Qt are 5.8 or higher.
. Use `dictcli.py` script to install dictionaries.
  Run the script with `-h` for the parameter description.
. Set `spellcheck.languages` to the desired list of languages, e.g.:
  `:set spellcheck.languages "['en-US', 'pl-PL']"`

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.

Why does J move to the next (right) tab, and K to the previous (left) one?::
    One reason is because https://bitbucket.org/portix/dwb[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`).

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 shift+escape bound. This is
    because shift+escape is unlikely to be a useful binding to be passed to a
    webpage. However, any other keys may be assigned to leaving passthrough mode
    instead of shift+escape should this be desired.

Why does it take longer to open a URL in qutebrowser than in chromium?::
    When opening a 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
    to which the URL is then passed. This takes some time.
    One workaround is to use this
    https://github.com/qutebrowser/qutebrowser/blob/master/scripts/open_url_in_instance.sh[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.

How do I make qutebrowser use greasemonkey scripts?::
    There is currently no UI elements to handle managing greasemonkey scripts.
    All management of what scripts are installed or disabled is done in the
    filesystem by you. qutebrowser reads all files that have an extension of
    `.js` from the `<data>/greasemonkey/` folder and attempts to load them.
    Where `<data>` is the qutebrowser data directory shown in the `Paths`
    section of the page displayed by `:version`. If you want to disable a
    script just rename it, for example, to have `.disabled` on the end, after
    the `.js` extension. To reload scripts from that directory run the command
    `:greasemonkey-reload`.
+
Troubleshooting: to check that your script is being loaded when
`:greasemonkey-reload` runs you can start qutebrowser with the arguments
`--debug --logfilter greasemonkey,js` and check the messages on the
program's standard output for errors parsing or loading your script.
You may also see javascript errors if your script is expecting an environment
that we fail to provide.
+
Note that there are some missing features which you may run into:

. Some scripts expect `GM_xmlhttpRequest` to ignore Cross Origin Resource
  Sharing restrictions, this is currently not supported, so scripts making
  requests to third party sites will often fail to function correctly.
. If your backend is a QtWebEngine version 5.8, 5.9 or 5.10 then regular
  expressions are not supported in `@include` or `@exclude` rules. If your
  script uses them you can re-write them to use glob expressions or convert
  them to `@match` rules.
  See https://wiki.greasespot.net/Metadata_Block[the wiki] for more info.
. Any greasemonkey API function to do with adding UI elements is not currently
  supported. That means context menu extentensions and background pages.

How do I change the `WM_CLASS` used by qutebrowser windows?::
    Qt only supports setting `WM_CLASS` globally, which you can do by starting
    with `--qt-arg name foo`. Note that all windows are part of the same
    qutebrowser instance (unless you use `--temp-basedir` or `--basedir`), so
    they all will share the same `WM_CLASS`.

== Troubleshooting

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
    https://get.adobe.com/flashplayer/[Adobe]. Note that QtWebEngine needs
    PPAPI Flash, while QtWebKit needs NPAPI Flash.

Unable to view DRM content (Netflix, Spotify, etc.).::
    On Arch Linux, simply install `chromium-widevine` from the AUR.
+
For other distributions, it should be possible to obtain the needed
widevine files and store them in the correct places, but the details differ
wildly between various Qt versions.

Unable to use `spawn` on MacOS.::
    When running qutebrowser from the prebuilt binary (`qutebrowser.app`) it
    *will not* read any files that would alter your `$PATH` (e.g. `.profile`,
    `.bashrc`, etc). This is not a bug, just that `.profile` is not propagated
    to GUI applications in MacOS.
+
See https://github.com/qutebrowser/qutebrowser/issues/4273[Issue #4273] for
details and potential workarounds.

QtWebKit: 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 https://github.com/qutebrowser/qutebrowser/issues/357[Issue #357]
    for more details.

My issue is not listed.::
    If you experience any segfaults or crashes, you can report the issue in
    https://github.com/qutebrowser/qutebrowser/issues[the issue tracker] or
    using the `:report` command.
    If you are reporting a segfault, make sure you read the
    link:stacktrace{outfilesuffix}[guide] on how to report them with all needed
    information.

[[sponsors]]
== GitHub Sponsors FAQ

Using https://github.com/sponsors/The-Compiler[GitHub Sponsors], you can sign
up for a monthly donation to The-Compiler (qutebrowser's main developer),
allowing him to work part-time on qutebrowser. If you keep your donation level
for long enough, you can get some qutebrowser stickers!

Why GitHub Sponsors? What is the GitHub Matching Fund?::
    Thanks to the
    https://help.github.com/en/github/supporting-the-open-source-community-with-github-sponsors/about-github-sponsors#about-the-github-sponsors-matching-fund[GitHub Sponsors Matching Fund],
    all donations are doubled by GitHub in the first year, up to a $5000 total limit.
+
Even outside of the matching fund, GitHub Sponsors is nicely integrated with
qutebrowser's existing GitHub page and a better offering than alternatives such
as Patreon or Liberapay.

Is it possible to contribute via a one-time donation instead?::
   If you prefer a one-time donation, there are various possibilities:
+
- Select a tier which covers the total amount you'd like to donate (note that
  payments are prorated based on the current date). After the payment is
  processed, cancel your GitHub sponsors subscription again. This has a big
  benefit: Thanks to GitHub's matching fund, your donation will be doubled (and
  nothing will be lost to fees).
+
- Sign up for a lower recurring donation instead.
+
- Do so via the https://github.com/qutebrowser/qutebrowser#donating[existing
  donation methods]. Rewards (shirts/stickers/swag) are handled on a
  case-by-case basis as GitHub's matching fund isn't applicable and there might
  be relatively high fees which make this tricky.
+
- If you want to contribute via a one-time donation and want to make sure
  you'll receive a reward, you might want to sign up to the
  https://lists.schokokeks.org/mailman/listinfo.cgi/qutebrowser-announce[qutebrowser-announce]
  mailinglist and wait until there is an official way to do so. It's planned to
  set this up at a later date. Note that the thresholds for perks will be
  higher because those donations aren't matched by GitHub and fees are
  relatively high.

I'd like a certain reward (e.g. a t-shirt) but I'd prefer making a smaller monthly donation. Can I upgrade via a one-time donation?::
    It's planned to set up a donation page to allow this at a later date.
    However, the thresholds for perks will be higher because those donations
    aren't matched by GitHub and fees are relatively high. Note that you can
    switch tiers on GitHub sponsors at any time.

GitHub tries to charge me for an entire year. What gives?::
    This happens if you have an existing annual billing cycle with GitHub (for
    example a Pro membership or Marketplace subscription). At the moment,
    GitHub's billing system only supports annual sponsor payments in that case.

Can I support you without getting any rewards/merchandise?::
    Absolutely! Any merchandise is optional. Before sending out merchandise
    I'll distribute forms asking for size/address/etc. - those forms will have
    an option to not get any merch at all.

Can I select my own amount rather than using the predefined tiers?::
    Unfortunately, GitHub sponsors doesn't support this at the moment. The
    existing tiers should hopefully cover various options. If you disagree,
    please mailto:mail@qutebrowser.org[get in touch] - I might be able to add a
    new sponsorship tier.

When will rewards be shipped?::
    Rewards will be ordered and subsequently shipped once it's clear how many
    people are eliglible. The cut-off date for the donation goals is May
    2020, so rewards will likely be shipped Q2/2020. This also applies to tiers
    which make you eliglible for a certain perk immediately, though stickers
    might be shipped earlier depending on how many people this affects.

I'd like some stickers, but I can't donate anything because of my financial situation.::
    Please mailto:mail@qutebrowser.org[get in touch]! As long as this doesn't
    get abused, I'd happily send stickers for free.

We're a company interested in sponsoring qutebrowser, can you invoice us for the sponsored amount?::
    You will receive a confirmation mail including a PDF receipt from GitHub
    when sponsoring qutebrowser. If you really need an invoice, I can bill
    you via my company, https://bruhin.software/[Bruhin Software]. Please
    mailto:mail@qutebrowser.org[get in touch] to discuss details!

Can you share details on the stickers?::
    There are two sticker designs: Rectangular stickers (with text) and round
    vinyl stickers. Those are the same as during the 2016/2017 crowdfundings.
+
image:https://qutebrowser.org/img/sponsors/stickers.jpg["stickers",width=300,link="https://qutebrowser.org/img/sponsors/stickers.jpg"]

Can you share details on the swag?::
    A limited number of metal buttons and magnets is available:
+
image:https://qutebrowser.org/img/sponsors/swag.jpg["swag",width=300,link="https://qutebrowser.org/img/sponsors/swag.jpg"]
+
It's planned to order more swag, depending on the exact demand. Possibilites
would include:
+
- qutebrowser pens (refillable)
- notebooks (the paper kind)
- USB-sticks (for the "expensive swag" reward).

Can you share details on the t-shirts?::
    The shirts will be
    https://www.bc-collection.eu/en/t-shirts/bc-e190-tu03t[B&C #E190] shirts
    which are the successor to the "Exact 190" shirts distributed in the
    previous crowdfundings: 100% cotton and relatively thick/heavy.
+
Sizes from XS and 5XL are available, most of them also as a fitted (women) cut.
Up to 40 colors are available from the supplier - there will be a selection of
recommended/tested colors, but any available color can be selected on your own
risk.
+
The print will be a white silk-screen print, with the same design as in the
2016 crowdfunding:
+
image:https://qutebrowser.org/img/sponsors/shirt.jpg["shirt",width=300,link="https://qutebrowser.org/img/sponsors/shirt.jpg"]

[[privacy]]
== Privacy Policy

Being a mostly volunteer-run project, qutebrowser does not have the resources
for a full legalese version of a privacy policy. Instead, this overview should
answer the most common questions.

For any privacy questions, please contact mailto:privacy@qutebrowser.org[].

=== Website

The qutebrowser.org website does not use any cookies or trackers.

However, IP addresses are currently (October 2019) logged and stored
indefinitely. It's planned to change this soon by migrating qutebrowser.org to
a different server.

Note that some services related to qutebrowser are stored on third-party
services such as GitHub, Travis CI or AppVeyor. By using their websites, you're
subject to their privacy policies.

=== Crash reports

When qutebrowser crashes or you use the `:report` command, you have the
possibility to send a crash report. If you decide to do so, your crash report
is stored on qutebrowser's server, where core qutebrowser developers (four
people at the time of writing) can access it.

If you select the option to include a debug log with your report, it's possible
that sensitive information is contained in your report. You can show and edit
the log in the crash report window to redact any such information as you see
fit. Additionally, qutebrowser tries to avoid logging information such as
passwords entirely (by not logging any input going to websites).

Currently, crash reports are stored indefinitely for technical reasons. With a
https://github.com/The-Compiler/crashbin/[new tool designed for crash reports],
it'll become possible to delete crashreports after the underlying issue is
fixed, but that tool needs some more work before qutebrowser can use it.

=== Application

Without any user interaction, qutebrowser can be expected to make no
unsolicited requests. It does not contain any telemetry code.

The QtWebEngine library (on which qutebrowser is based on) strips out any
Chromium features which talk to Google servers, so any unsolicited requests
should be treated as a bug.

While qutebrowser uses DuckDuckGo as the default search page, no advertising
deal exists between DuckDuckGo and qutebrowser. Note that by visiting
DuckDuckGo, you're subject to their privacy policy.

With regard to websites you visit, qutebrowser tries to strike a balance
between usability/compatibility and privacy. There are various `content.*`
settings which can be used to tweak such behavior, reduce fingerprinting or
disable various features (usually at a cost of website compatibility).