path: root/doc/install.asciidoc

Installing qutebrowser
======================

toc::[]

Official vs. community-maintained
---------------------------------

Only the following releases are done by qutebrowser's maintainer directly:

- Source packages in https://github.com/qutebrowser/qutebrowser/releases[this
  GitHub repository] and on https://pypi.org/project/qutebrowser/#files[PyPI]
- Windows and macOS prebuilt binaries in the GitHub Releases
- The `qutebrowser-git` package in the
  https://aur.archlinux.org/packages/qutebrowser-git/[Archlinux AUR]
- Installing <<tox,in a virtualenv>> from the git repository.

All other packaging is done by the community, so in case of outdated/broken
packages, you will need to reach out to the respective maintainers. Note that
some distributions (notably, Debian Stable and Ubuntu) do only update
qutebrowser and the underlying QtWebEngine when there's a new release of the
distribution, typically once all couple of months to years.

On Debian / Ubuntu
------------------

How to install qutebrowser depends a lot on the version of Debian/Ubuntu you're
running.

[[ubuntu1604]]
Debian Stretch / Ubuntu 16.04 LTS / Linux Mint 18
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Debian Stretch does have QtWebEngine packaged, but only in a very old and insecure
version (Qt 5.7, based on a Chromium from March 2016). Furthermore, it packages Python
3.5 which is not supported anymore since qutebrowser v2.0.0.

Ubuntu 16.04 doesn't come with an up-to-date engine (a new enough QtWebKit, or
QtWebEngine) and also comes with Python 3.5.

You should be able to install a newer Python (3.6+) using the
https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa[deadsnakes PPA] or
https://github.com/pyenv/pyenv[pyenv], and then proceed to
<<tox,install qutebrowser in a virtualenv>>. However, this is currently untested. If you
got this setup to work successfully, please submit a pull request to adjust these
instructions!

Note you'll need some basic libraries to use the virtualenv-installed PyQt:

----
# apt install --no-install-recommends git ca-certificates python3 python3-venv asciidoc libglib2.0-0 libgl1 libfontconfig1 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0 libdbus-1-3 libyaml-dev gcc python3-dev libnss3
----

// FIXME not needed anymore?
// libxi6 libxrender1 libegl1-mesa

Debian Buster / Ubuntu 18.04 LTS / Linux Mint 19
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Debian Buster packages qutebrowser, but ships a very old version (v1.6.1 from March
2019). The QtWebEngine library used for rendering web contents is also very old (Qt
5.11, based on a Chromium from March 2018) and insecure. It is
https://www.debian.org/releases/buster/amd64/release-notes/ch-information.en.html#browser-security[not covered]
by Debian's security patches. It's recommended to <<tox,install qutebrowser in a
virtualenv>> with a newer PyQt/Qt binary instead.

With Ubuntu 18.04, the situation looks similar (but worse): There, qutebrowser v1.1.1
from January 2018 is packaged, with QtWebEngine 5.9 based on a Chromium from January
2017. It's recommended to either upgrade to Ubuntu 20.04 LTS or <<tox,install
qutebrowser in a virtualenv>> with a newer PyQt/Qt binary instead.

Ubuntu 20.04 LTS / Linux Mint 20 (or newer)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

With those distributions, qutebrowser is in the official repositories, and you
can install it with apt:

----
# apt install qutebrowser
----

Additional hints
~~~~~~~~~~~~~~~~

- If running from git, run the following to generate the documentation for the
  `:help` command (the `mkvenv.py` script used with a virtualenv install already does
  this for you):
+
----
# apt install --no-install-recommends asciidoc
$ python3 scripts/asciidoc2html.py
----

- If you prefer using QtWebKit, there's QtWebKit 5.212 available in
  Ubuntu 18.04 / Debian Buster or newer.  Note however that it is based on an upstream
  WebKit from September 2016 with known security issues and no sandboxing or process
  isolation.
- If video or sound don't work with QtWebKit, try installing the gstreamer plugins:
+
----
# apt install gstreamer1.0-plugins-{bad,base,good,ugly}
----
+
Note those are only needed with QtWebKit, not with the (default) QtWebEngine backend.

On Fedora
---------

qutebrowser is available in the official repositories:

-----
# dnf install qutebrowser
-----

Additional hints
~~~~~~~~~~~~~~~~

Fedora only ships free software in the repositories.
To be able to play videos with proprietary codecs with QtWebEngine, you will
need to install an additional package from the RPM Fusion Free repository.
For more information see https://rpmfusion.org/Configuration.

-----
# dnf install qt5-qtwebengine-freeworld
-----

On Archlinux
------------

qutebrowser is available in the official [community] repository.

----
# pacman -S qutebrowser
----

There is also a -git version available in the AUR:
https://aur.archlinux.org/packages/qutebrowser-git/[qutebrowser-git].

You can install it using `makepkg` like this:

----
$ git clone https://aur.archlinux.org/qutebrowser-git.git
$ cd qutebrowser-git
$ makepkg -si
$ cd ..
$ rm -r qutebrowser-git
----

or you could use an AUR helper like https://github.com/Jguer/yay/[yay], e.g.
`yay -S qutebrowser-git`.

If video or sound don't work with QtWebKit, try installing the gstreamer plugins:

----
# pacman -S gst-plugins-{base,good,bad,ugly} gst-libav
----

On Gentoo
---------

qutebrowser is available in the main repository and can be installed with:

----
# emerge -av qutebrowser
----

If video or sound don't work with QtWebKit, try installing the gstreamer
plugins:

----
# emerge -av gst-plugins-{base,good,bad,ugly,libav}
----

To be able to play videos with proprietary codecs with QtWebEngine, you will
need to turn off the `bindist` flag for `dev-qt/qtwebengine`.

See the https://wiki.gentoo.org/wiki/Qutebrowser#USE_flags[Gentoo Wiki] for
more information.

On Void Linux
-------------

qutebrowser is available in the official repositories and can be installed
with:

----
# xbps-install qutebrowser
----

On NixOS
--------

Nixpkgs collection contains `pkgs.qutebrowser` since June 2015. You can install
it with:

----
$ nix-env -i qutebrowser
----

On openSUSE
-----------

There are prebuilt RPMs available at https://software.opensuse.org/download.html?project=network&package=qutebrowser[OBS].

On Slackware
------------

qutebrowser is available in the 3rd party repository at https://slackbuilds.org[slackbuilds.org]

An easy way to install it is with sbopkg (frontend for slackbuilds.org) available at https://sbopkg.org[sbopkg.org]

sbopkg can be run with a dialog screen interface, or via command line options.

After installing the latest sbopkg package, choose your release version, and sync the repo.

----
sbopkg -V 14.2
sbopkg -r
----

Generate a queue file for qutebrowser and dependencies:

----
sqg -p qutebrowser
----

Then load the queue in the dialog queue menu or via:

----
PYTHON3=yes sbopkg -i qutebrowser
----

If you use the dialog screen you can deselect any already-installed packages that you don't need/want to rebuild before starting the build process.

Via Flatpak
-----------

qutebrowser is available
https://flathub.org/apps/details/org.qutebrowser.qutebrowser[on Flathub]
as `org.qutebrowser.qutebrowser`.

NOTE: The Flatpak package is
https://github.com/flathub/org.qutebrowser.qutebrowser/issues/8#issuecomment-799579975[looking for (co-)maintainers].
The package recently was updated after being out of date for multiple years. It
currently (March 2021) is up to date again. If that situation changes, consider
to <<tox,install qutebrowser in a virtualenv>> instead, which is one of the
officially maintained options and will always be up-to-date.

On FreeBSD
----------

qutebrowser is in https://www.freshports.org/www/qutebrowser/[FreeBSD ports].

It can be installed with:

----
# cd /usr/ports/www/qutebrowser
# make install clean
----

At present, precompiled packages are not available for this port,
and QtWebEngine backend is also not available.

On Windows
----------

There are different ways to install qutebrowser on Windows:

Prebuilt binaries
~~~~~~~~~~~~~~~~~

Prebuilt standalone packages and installers
https://github.com/qutebrowser/qutebrowser/releases[are built] for every
release.

Note that you'll need to upgrade to new versions manually (subscribe to the
https://lists.schokokeks.org/mailman/listinfo.cgi/qutebrowser-announce[qutebrowser-announce
mailinglist] to get notified on new releases). You can install a newer version
without uninstalling the older one.

The binary release ships with a QtWebEngine built without proprietary codec
support. To get support for e.g. h264/mp4 videos, you'll need to build
QtWebEngine from source yourself with support for that enabled.

Nightly builds
~~~~~~~~~~~~~~

If you want to test out new features before an official qutebrowser release, automated
https://github.com/qutebrowser/qutebrowser/actions/workflows/bleeding.yml[nightly
builds] are available. To download them, open the lastest run (usually the first one),
then download the archive at the bottom of the page. Note that due to GitHub
limitations, all variants (Windows/macOS, 32/64 bit, debug/non-debug) are contained in a
single archive.

Those builds also include variants with debug logging enabled, which can be useful to
track down issues.

https://chocolatey.org/packages/qutebrowser[Chocolatey package]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* PackageManagement PowerShell module
----
PS C:\> Install-Package qutebrowser
----
* Chocolatey's client
----
C:\> choco install qutebrowser
----
* Scoop's client
----
C:\> scoop bucket add extras
C:\> scoop install qutebrowser
----

Manual install
~~~~~~~~~~~~~~

Use the installer from https://www.python.org/downloads[python.org] to get
Python 3 (be sure to install pip).

Then <<tox,install qutebrowser via virtualenv>>.

On macOS
--------

Prebuilt binary
~~~~~~~~~~~~~~~

The easiest way to install qutebrowser on macOS is to use the prebuilt `.app`
files from the
https://github.com/qutebrowser/qutebrowser/releases[release page].

Note that you'll need to upgrade to new versions manually (subscribe to the
https://lists.schokokeks.org/mailman/listinfo.cgi/qutebrowser-announce[qutebrowser-announce
mailinglist] to get notified on new releases).

The binary release ships with a QtWebEngine built without proprietary codec
support. To get support for e.g. h264/mp4 videos, you'll need to build
QtWebEngine from source yourself with support for that enabled.

This binary is also available through the
https://caskroom.github.io/[Homebrew Cask] package manager:

----
$ brew install qutebrowser --cask
----

Nightly builds
~~~~~~~~~~~~~~

If you want to test out new features before an official qutebrowser release, automated
https://github.com/qutebrowser/qutebrowser/actions/workflows/bleeding.yml[nightly
builds] are available. To download them, open the lastest run (usually the first one),
then download the archive at the bottom of the page. Note that due to GitHub
limitations, all variants (Windows/macOS, 32/64 bit, debug/non-debug) are contained in a
single archive.

Those builds also include variants with debug logging enabled, which can be useful to
track down issues.

Manual Install
~~~~~~~~~~~~~~

Alternatively, you can install the dependencies via a package manager (like
https://brew.sh/[Homebrew] or https://www.macports.org/[MacPorts]) and run
qutebrowser from source.

==== Homebrew

----
$ brew install qt
(build PyQt and PyQtWebEngine from source)
$ pip3 install qutebrowser
----

NOTE: Homebrew does not package PyQtWebEngine (Python wrappers for
QtWebEngine), so you will need to build that from sources manually.

Since the v1.0 release, qutebrowser uses QtWebEngine by default.

Homebrew's builds of Qt and PyQt don't come with QtWebKit (and `--with-qtwebkit`
uses an old version of QtWebKit which qutebrowser doesn't support anymore). If
you want QtWebKit support, you'll need to build an up-to-date QtWebKit
https://github.com/annulen/webkit/wiki/Building-QtWebKit-on-OS-X[manually].

Packagers
---------

qutebrowser ships with a
https://github.com/qutebrowser/qutebrowser/blob/master/misc/Makefile[Makefile]
intended for packagers. This installs system-wide files in a proper locations,
so it should be preferred to the usual `setup.py install` or `pip install`
invocation.

// The tox anchor is so that old links remain compatible.
// When switching to Sphinx, that should be changed.

[[tox]]
Installing qutebrowser with virtualenv
--------------------------------------

IMPORTANT: Before January 2020, this section used to be about installing
qutebrowser via `tox` which is a wrapper around `virtualenv`. Now, a dedicated
script is used instead.

A https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments[virtual environment]
(virtualenv, venv) allows Python packages to be installed in an isolated
location for a particular application, rather than being installed globally.

The `scripts/mkvenv.py` script in this repository can be used to create a
virtualenv for qutebrowser and install it (including all dependencies) there.
The next couple of sections will explain the most common use-cases - run
`mkvenv.py` with `--help` to see all available options.

Getting the repository
~~~~~~~~~~~~~~~~~~~~~~

First of all, clone the repository using https://git-scm.org/[git] and switch
into the repository folder:

----
$ git clone https://github.com/qutebrowser/qutebrowser.git
$ cd qutebrowser
----

Installing dependencies (including Qt)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Using a Qt installed via virtualenv needs a couple of system-wide libraries.
See the <<ubuntu1604,Ubuntu 16.04 section>> for details about which libraries
are required.

Then run the install script:

----
$ python3 scripts/mkvenv.py
----

This installs all needed Python dependencies in a `.venv` subfolder
(which subdirectory the environment is created in is configurable via the
`--venv-dir` flag).

This comes with an up-to-date Qt/PyQt including a pre-compiled QtWebEngine
binary, but has a few caveats:

- Make sure your `python3` is Python 3.6 or newer, otherwise you'll get a "No
  matching distribution found" error and/or qutebrowser will not run.
- It only works on 64-bit x86 systems, with other architectures you'll get the
  same error.
- It comes with a QtWebEngine compiled without proprietary codec support (such
  as h.264).

See the next section for an alternative install method which might help with
those issues but result in an older Qt version.

You can specify a Qt/PyQt version with the `--pyqt-version` flag, see
`mkvenv.py --help` for a list of available versions. By default, the latest
version which plays well with qutebrowser is used.

NOTE: If the Qt smoke test fails with a _"This application failed to start
because no Qt platform plugin could be initialized."_ message, most likely a
system-wide library is missing. Pay attention to a _QLibraryPrivate::loadPlugin
failed on ..._ line for details.

Installing dependencies (system-wide Qt)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Alternatively, you can use `mkvenv.py --pyqt-type link` to symlink your local
PyQt/Qt install instead of installing PyQt in the virtualenv. However, unless
you have a new QtWebKit or QtWebEngine available, qutebrowser will not work. It
also typically means you'll be using an older release of QtWebEngine.

On Windows, run `set PYTHON=C:\path\to\python.exe` (CMD) or ``$Env:PYTHON =
"..."` (Powershell) first.

There is a third mode, `mkvenv.py --pyqt-type source` which uses a system-wide
Qt but builds PyQt from source. In most scenarios, this shouldn't be needed.

Creating a wrapper script
~~~~~~~~~~~~~~~~~~~~~~~~~

Running `mkvenv.py` does not install a system-wide `qutebrowser` script. You can
launch qutebrowser by doing:

----
.venv/bin/python3 -m qutebrowser
----

You can create a simple wrapper script to start qutebrowser somewhere in your
`$PATH` (e.g. `/usr/local/bin/qutebrowser` or `~/bin/qutebrowser`):

----
#!/bin/bash
~/path/to/qutebrowser/.venv/bin/python3 -m qutebrowser "$@"
----

Building the docs
~~~~~~~~~~~~~~~~~

To build the documentation, install `asciidoc` (note that LaTeX which comes as
optional/recommended dependency with some distributions is not required).

Then, run:

----
$ python3 scripts/asciidoc2html.py
----

Updating
~~~~~~~~

If you cloned the git repository, run `mkvenv.py --update` which will take care
of updating the code (via `git pull`) and recreating the environment with the
newest dependencies.

Alternatively, you can update your local copy of the code (e.g. by pulling the
git repo, or extracting a new version) and the virtualenv should automatically
use the updated versions. However, dependencies won't be updated that way.