qutebrowser/doc/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)

Install the dependencies via apt-get:

----
# apt-get install python3-pyqt5 python3-pyqt5.qtwebkit
----

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

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

Then run the supplied script to run qutebrowser inside a
https://docs.python.org/3/library/venv.html[virtual environment]:

----
# python3 scripts/init_venv.py
----

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

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

There are two Archlinux packages available in the AUR:
https://aur.archlinux.org/packages/qutebrowser/[qutebrowser] and
https://aur.archlinux.org/packages/qutebrowser-git/[qutebrowser-git].

You can install them like this:

----
$ mkdir qutebrowser
$ cd qutebrowser
$ wget https://aur.archlinux.org/packages/qu/qutebrowser-git/PKGBUILD
$ makepkg -si
----

or you could use an AUR helper, e.g. `yaourt -S qutebrowser-git`.

On Gentoo
---------

A dedicated overlay is available on
https://github.com/posativ/qutebrowser-overlay[GitHub]. To install it, add the
overlay with http://wiki.gentoo.org/wiki/Layman[layman]:

----
# layman -a qutebrowser
----

Note, that Qt5 is available in the portage tree, but masked. You may need to do
a lot of keywording to install qutebrowser. Also make sure you have `python3_4`
in your `PYTHON_TARGETS` (`/etc/portage/make.conf`) and rebuild your system
(`emerge -uDNav @world`). Afterwards, you can install qutebrowser:

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

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

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

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

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

You can either use one of the
https://github.com/The-Compiler/qutebrowser/releases[prebuilt standalone
packages or MSI installers], or install manually:

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

Then run the supplied script to run qutebrowser inside a
https://docs.python.org/3/library/venv.html[virtual environment]:

----
# python3 scripts/init_venv.py
----

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

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]. Also make
sure, you have https://itunes.apple.com/en/app/xcode/id497799835[XCode]
installed to compile PyQt5 in a later step.

----
$ brew install python3 pyqt5
$ pip3.4 install qutebrowser
----

if you are using Homebrew. 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.