path: root/INSTALL.asciidoc

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

toc::[]

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 <<tox,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
----

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
https://github.com/qutebrowser/qutebrowser/releases[release page] and download
the https://qutebrowser.org/python3-pypeg2_2.15.2-1_all.deb[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
----

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}
----

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

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:
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, 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
https://gist.github.com/annulen/309569fb61e5d64a703c055c1e726f71[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}
----


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 for Tumbleweed and Leap 42.1:

http://software.opensuse.org/download.html?project=home%3Aarpraher&package=qutebrowser[One Click Install]

Or add the repo manually:

----
# zypper addrepo http://download.opensuse.org/repositories/home:arpraher/openSUSE_Tumbleweed/home:arpraher.repo
# zypper refresh
# zypper install qutebrowser
----

On OpenBSD
----------

qutebrowser is in http://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/www/qutebrowser/[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
https://github.com/qutebrowser/qutebrowser/releases[are built] for every
release.

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

* PackageManagement PowerShell module
----
PS C:\> Install-Package qutebrowser
----
* Chocolatey's client
----
C:\> choco install qutebrowser
----

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

* Use the installer from http://www.python.org/downloads[python.org] to get
Python 3 (be sure to install pip).
* Use the installer from
http://www.riverbankcomputing.com/software/pyqt/download5[Riverbank computing]
to get Qt and PyQt5.
* Install https://testrun.org/tox/latest/index.html[tox] via
https://pip.pypa.io/en/latest/[pip]:

----
$ pip install tox
----

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

On OS X
-------

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

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

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

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

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

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

==== Homebrew

----
$ 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
----

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.

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

First of all, clone the repository using http://git-scm.org/[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
https://docs.python.org/3/library/venv.html[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`):

----
#!/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
----