Table of Contents
Note
 qutebrowser recently had some bigger dependency changes for v1.0.0, which means those instructions might be out of date in some places. Please help updating them if you notice something being broken!

On Debian / Ubuntu

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

Debian Jessie / Ubuntu 14.04 LTS / Linux Mint < 18

Those distributions only have Python 3.4 and a too old Qt version available, while qutebrowser requires Python 3.5 and Qt 5.7.1 or newer.

It should be possible to install Python 3.5 e.g. from the deadsnakes PPA or via_ipca pyenv, but nobody tried that yet.

If you get qutebrowser running on those distributions, please contribute to update this documentation!

Ubuntu 16.04 LTS / Linux Mint 18

Ubuntu 16.04 doesn’t come with an up-to-date engine (a new enough QtWebKit, or QtWebEngine). However, it comes with Python 3.5, so you can install qutebrowser via tox.

Debian Stretch / Ubuntu 17.04 and newer

Those versions come with QtWebEngine in the repositories. This makes it possible to install qutebrowser via the Debian package.

Get the qutebrowser package from the release page and download the PyPEG2 package.

(If you are using debian testing you can just use the python3-pypeg2 package from the repos)

Install the packages:

# apt install ./python3-pypeg2_*_all.deb
# apt install ./qutebrowser_*_all.deb

Some additional hints:

  • Alternatively, you can install qutebrowser via tox to get a newer QtWebEngine version.

  • If running from git, run the following to generate the documentation for the :help command: 

    # apt install --no-install-recommends asciidoc source-highlight
$ python3 scripts/asciidoc2html.py

  • If you prefer using QtWebKit, there’s an up-to-date version available in Debian experimental, or from this repository for Debian Stretch.

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

    # apt install gstreamer1.0-plugins-{bad,base,good,ugly}

On Fedora

The Fedora packages are lagging behind a lot and are currently effectively unmaintained. It’s recommended to install qutebrowser via tox instead.

Related Fedora bug: 1467748

On Archlinux

qutebrowser is available in the official [community] repository.

# pacman -S qutebrowser

There is also a -git version available in the AUR: 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, e.g. yaourt -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

The Gentoo packages (even the live version) are lagging behind a lot and are effectively unmaintained. Efforts to fix this (via proxy maintainers) are currently underway. In the meantime, it’s recommended to install qutebrowser via tox instead.

Related Gentoo bugs with patches: -9999, v1.0

To get an up-to-date QtWebKit, you can use this ebuild.

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 Gentoo Wiki for more information.

On Void Linux

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

# xbps-install qutebrowser

It’s currently recommended to install python3-PyQt5-webengine and python3-PyQt5-opengl, then start with --backend webengine to use the new backend.

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

On NixOS

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

$ nix-env -i qutebrowser

It’s recommended to install qt5.qtwebengine and start with --backend webengine to use the new backend.

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

On openSUSE

There are prebuilt RPMs available at OBS.

To use the QtWebEngine backend, install libqt5-qtwebengine.

On OpenBSD

qutebrowser is in OpenBSD ports.

Install the package:

# pkg_add qutebrowser

Or alternatively, use the ports system :

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

On Windows

There are different ways to install qutebrowser on Windows:

Prebuilt binaries

Prebuilt standalone packages and installers are built for every release.

Note that you’ll need to upgrade to new versions manually (subscribe to the 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/h265 videos, you’ll need to build QtWebEngine from source yourself with support for that enabled.

Chocolatey package

  • PackageManagement PowerShell module 

PS C:\> Install-Package qutebrowser

  • Chocolatey’s client 

C:\> choco install qutebrowser

Manual install

  • Use the installer from python.org to get Python 3 (be sure to install pip).

  • Install tox via pip: 

$ pip install tox

Then install qutebrowser via tox.

On macOS

Prebuilt binary

The easiest way to install qutebrowser on macOS is to use the prebuilt .app files from the release page.

Note that you’ll need to upgrade to new versions manually (subscribe to the 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/h265 videos, you’ll need to build QtWebEngine from source yourself with support for that enabled.

This binary is also available through the Homebrew Cask package manager:

$ brew cask install qutebrowser

Manual Install

Alternatively, you can install the dependencies via a package manager (like Homebrew or MacPorts) and run qutebrowser from source.

Homebrew

$ brew install qt5
$ pip3 install qutebrowser

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

Packagers

There are example .desktop and icon files provided. They would go in the standard location for your distro (/usr/share/applications and /usr/share/pixmaps for example).

The normal setup.py install doesn’t install these files, so you’ll have to do it as part of the packaging process.

Installing qutebrowser with tox

Getting the repository

First of all, clone the repository using git and switch into the repository folder:

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

Installing depdendencies (including Qt)

Then run tox inside the qutebrowser repository to set up a virtual environment:

$ tox -e mkvenv-pypi

This installs all needed Python dependencies in a .venv subfolder.

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

  • Make sure your python3 is Python 3.5 or newer, otherwise you’ll get a "No matching distribution found" error. Note that qutebrowser itself also requires this.

  • It only works on 64-bit x86 systems, with other architectures you’ll get the same error.

  • If your distribution uses OpenSSL 1.1 (like Debian Stretch or Archlinux), you’ll need to set LD_LIBRARY_PATH to the OpenSSL 1.0 directory (export LD_LIBRARY_PATH=/usr/lib/openssl-1.0 on Archlinux) before starting qutebrowser if you want SSL to work in certain downloads (e.g. for :adblock-update or :download).

  • It comes with a QtWebEngine compiled without proprietary codec support (such as h.264).

See the next section for an alternative.

Installing dependencies (system-wide Qt)

Alternatively, you can use tox -e mkvenv (without -pypi) to symlink your local 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 `tox -e mkvenv-win instead, however make sure that ONLY Python3 is in your PATH before running tox.

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

Creating a wrapper script

You can then 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 "$@"

Updating

When you updated your local copy of the code (e.g. by pulling the git repo, or extracting a new version), the virtualenv should automatically use the updated code. However, if dependencies got added, this won’t be reflected in the virtualenv. Thus it’s recommended to run the following command to recreate the virtualenv:

$ tox -r -e mkvenv-pypi