path: root/INSTALL.asciidoc

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

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.

Using the packages
~~~~~~~~~~~~~~~~~~

Install the dependencies via apt-get:

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

Get the packages from the https://github.com/The-Compiler/qutebrowser/releases[release page]

Install the packages:

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

Build it from git
~~~~~~~~~~~~~~~~~

Install the dependencies via apt-get:

[NOTE]
==========================
On Debian, it's recommended to install the Qt packages from the
https://wiki.debian.org/DebianExperimental[experimental] repository as those
are a much newer version of Qt which is more stable.

Add the following line to your `/etc/apt/sources.list`:

----
deb http://ftp.debian.org/debian experimental main
----

Then install the packages like this:

----
# apt-get update
# apt-get install -t experimental python3-pyqt5 python3-pyqt5.qtwebkit python3-sip python3-dev
# apt-get install python-tox
----

It's also recommended to pin those packages to receive updates by creating a
file `/etc/apt/preferences.d/qutebrowser` with the following contents:

----
Package: python3-pyqt5* libqt5*
Pin: release a=experimental
Pin-Priority: 800
----
==========================

For distributions other than Debian or if you prefer to not use the
experimental repo:

----
# apt-get install python3-pyqt5 python3-pyqt5.qtwebkit python-tox python3-sip python3-dev
----

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

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

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

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

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

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

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

There are different ways to install qutebrowser on Windows:

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

Prebuilt standalone packages and MSI installers
https://github.com/The-Compiler/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
-------

To install qutebrowser on OS X, you'll want a package manager, e.g.
http://brew.sh/[Homebrew] or https://www.macports.org/[MacPorts].

For Homebrew, a few extra steps are necessary since Homebrew dropped QtWebKit
from Qt 5.6.

This installs a Qt 5.5 and symlinks it so PyQt5 will work with it instead of Qt
5.6. This requires that `qt5` is not installed via Homebrew:

----
$ brew install python3 d-bus mysql sip xz
$ brew install homebrew/versions/qt55
$ brew install --ignore-dependencies pyqt5
$ ln -s /usr/local/opt/qt55 /usr/local/opt/qt5

$ pip3.5 install qutebrowser
----

For MacPorts, run:

----
$ sudo port install python34 py34-jinja2 asciidoc py34-pygments py34-pyqt5
$ sudo pip3.4 install qutebrowser
----

The preferences for qutebrowser are stored in
`~/Library/Preferences/qutebrowser`, the application data is stored in
`~/Library/Application Support/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/The-Compiler/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
----

This installs all needed Python dependencies in a `.venv` subfolder. The
system-wide Qt5/PyQt5 installations are symlinked into the virtual environment.

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

If you are developing on qutebrowser, you may want to redirect it to a local
config:

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

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