qutebrowser A keyboard-driven browser.

Installing qutebrowser

Table of Contents

On Debian / Ubuntu

qutebrowser should run on these systems:

  • Debian jessie or newer

  • Ubuntu Trusty (14.04 LTS) or newer

  • Any other distribution based on these (e.g. Linux Mint 17+)

Unfortunately there is no Debian package in the official repos yet, but installing qutebrowser is still relatively easy!

You can use packages that are built for every release or build it yourself from git.

On Ubuntu 16.04 and 16.10 it’s recommended to install qutebrowser via tox instead in order to be able to use the new QtWebEngine backend. Newer versions have a QtWebEngine package in the repositories.

Using the packages

Install the dependencies via apt-get:

# apt-get install python3-lxml python-tox python3-pyqt5 python3-pyqt5.qtwebkit python3-pyqt5.qtquick python3-sip python3-jinja2 python3-pygments python3-yaml python3-pyqt5.qtsql libqt5sql5-sqlite

On Debian Stretch or Ubuntu 17.04 or later, it’s also recommended to use the newer QtWebEngine backend.

To do so, install python3-pyqt5.qtwebengine and python3-pyqt5.qtopengl, then start qutebrowser with --backend webengine.

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

Install the packages:

# dpkg -i python3-pypeg2_*_all.deb
# dpkg -i qutebrowser_*_all.deb

Build it from git

Install the dependencies via apt-get:

# apt-get install python3-pyqt5 python3-pyqt5.qtwebkit python3-pyqt5.qtquick python-tox python3-sip python3-dev python3-pyqt5.qtsql libqt5sql5-sqlite

On Debian Stretch or Ubuntu 17.04 or later, it’s also recommended to install python3-pyqt5.qtwebengine and start qutebrowser with --backend webengine in order to use the new backend.

To generate the documentation for the :help command, when using the git repository (rather than a release):

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

If video or sound don’t seem to work, try installing the gstreamer plugins:

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

On Fedora

qutebrowser is available in the official repositories for Fedora 22 and newer.

# dnf install qutebrowser

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

On Archlinux

qutebrowser is available in the official [community] repository.

# pacman -S qutebrowser

Archlinux packages an updated qt5-webkit package by default. If you want to use the QtWebEngine backend instead, install qt5-webengine and start with --backend webengine.

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 seem to work, try installing the gstreamer plugins:

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

On Gentoo

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

# emerge -av qutebrowser

However it is suggested to install the Live version (-9999) to take advantage of the newest features introduced.

First of all you need to edit your package.accept_keywords file to accept the live version:

# nano /etc/portage/package.accept_keywords

And add the following line to it:

=www-client/qutebrowser-9999 **

Save the file and then install qutebrowser via

# emerge -av qutebrowser

Or rebuild your system if you already installed it.

To update to the last Live version, remember to do

# emerge -uDNav @live-rebuild @world

To include qutebrowser among the updates.

Make sure you have python3_4 in your PYTHON_TARGETS (/etc/portage/make.conf) and rebuild your system (emerge -uDNav @world) if necessary.

It’s also recommended to install QtWebKit-NG via this ebuild, or install Qt >= 5.7.1 with QtWebEngine in order to use an up-to-date backend.

If video or sound don’t seem to work, 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.

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.

On openSUSE

There are prebuilt RPMs available at OBS.

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.

Chocolatey package

  • PackageManagement PowerShell module

PS C:\> Install-Package qutebrowser
  • Chocolatey’s client

C:\> choco install qutebrowser

Manual install

$ pip install tox

On macOS

Prebuilt binary

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

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.


$ brew install qt5
$ pip3 install qutebrowser

Homebrew’s builds of Qt and PyQt no longer include QtWebKit - if you need QtWebKit support, it is necessary to build from source. The build takes several hours on an average laptop.

$ brew install qt5 --with-qtwebkit
$ brew install -s pyqt5
$ pip3 install qutebrowser


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

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

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

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

$ tox -e mkvenv-pypi

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.

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 QtWebKit-NG or QtWebEngine available, qutebrowser will use the legacy QtWebKit backend.

On Windows, run `tox -e mkvenv-win instead, however make sure that ONLY Python3 is in your PATH before running tox.

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

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

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


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