qutebrowser

A keyboard-driven, vim-like browser based on PyQt5 and QtWebKit.

qutebrowser is a keyboard-focused browser with with a minimal GUI. It’s based on Python, PyQt5 and QtWebKit and free software, licensed under the GPL.

It was inspired by other browsers/addons like dwb and Vimperator/Pentadactyl.

Screenshots

Documentation

In addition to the topics mentioned in this README, the following documents are available:

• Quick start guide

• Frequently asked questions

• HACKING

• Reporting segfaults

Getting help

You can get help in the IRC channel #qutebrowser on Freenode (webchat), or by writing a message to the mailinglist at qutebrowser@lists.qutebrowser.org.

Running qutebrowser

After installing the requirements, you have these options:

• Run qutebrowser directly via ./qutebrowser.py in the toplevel directory.

• Run python3 setup.py install to install qutebrowser, then call qutebrowser.

Note	If you’re running qutebrowser from the git repository rather than a released version, you should run scripts/asciidoc2html.py to generate the documentation.

Contributions / Bugs

You want to contribute to qutebrowser? Awesome! Please read HACKING for details and useful hints.

If you found a bug or have a feature request, you can report it in several ways:

• Use the built-in :report command or the automatic crash dialog.

• Open an issue in the Github issue tracker.

• Write a mail to the mailinglist at qutebrowser@lists.qutebrowser.org.

For security bugs, please contact me directly at mail@qutebrowser.org, GPG ID 0xFD55A072.

Requirements

The following software and libraries are required to run qutebrowser:

• Python 3.4

• Qt 5.2.0 or newer (5.3.2 recommended)

• QtWebKit

• PyQt 5.2.0 or newer (5.3.2 recommended) for Python 3

• pkg_resources/setuptools

• pyPEG2

• jinja2

• pygments

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

The following libraries are optional and provide colored logging in the console:

• colorlog

• On Windows: colorama

On Debian

# apt-get install python3-pyqt5 python3-pyqt5.qtwebkit python3-pkg-resources
python3-pip python3-jinja2 python3-pygments
# pip3 install pypeg2

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

# apt-get install asciidoc

On Archlinux

There’s an Archlinux package available in pkg/. You can install it (and the python-pypeg2 dependency) like this:

$ wget https://aur.archlinux.org/packages/py/python-pypeg2/python-pypeg2.tar.gz (1)
$ tar xzvf python-pypeg2.tar.gz
$ cd python-pypeg2
$ makepkg -si
$ cd ..

$ mkdir qutebrowser
$ cd qutebrowser
$ wget http://git.the-compiler.org/qutebrowser/plain/pkg/PKGBUILD.qutebrowser-git -O PKGBUILD
$ makepkg -si
$ cd ..
$ rm -rf python-pypeg2.tar.gz python-pypeg2 qutebrowser

1. Instead of the first block of commands you could also use an AUR helper, e.g. yaourt -S python-pypeg2.

As soon as v0.1 is out, there will be a package in the AUR, so this will get easier.

On Gentoo

Running qutebrowser on Gentoo is unfortunately rather hard because Qt5 and PyQt5 are not packaged officially. @posativ has written a howto with steps to get it running.

On Windows

• Use the installer from python.org to get Python 3

• Use the installer from Riverbank computing to get Qt and PyQt5.

• Run scripts/ez_setup.py to get setuptools.

• Get pip as described on Stack Overflow.

• Run pip install pypeg2 to install pypeg2.

• Run pip install jinja2 to install jinja2, or install it from http://www.lfd.uci.edu/~gohlke/pythonlibs/#jinja2.

• Run pip install pygments to install pygments, or install it from http://www.lfd.uci.edu/~gohlke/pythonlibs/#pygments.

As soon as v0.1 is out, a standalone .exe (built with cx_Freeze) will be provided. In the meantime, you can simply ask in IRC if you need one.

On OS X

Running qutebrowser on OS X requires compiling PyQt5 by hand. These steps have been tested on OS X Mavericks:

• Install XCode from the Appstore

• Open a Terminal

• Run xcode-select --install

• Install the XCode commandline tools

• Run sudo /usr/bin/xcodebuild and accept the license.

• Download and run the Qt5 installer. If you want, you can deselect Android/iOS when selecting the components to be installed.

• Run sed -i -e s/macosx10\.8/macosx10\.9/ ~/Qt/5.3/clang_64/mkspecs/qdevice.pri

• Download and install the Python 3 installer. After opening the .dmg, right-click on Python.mpkg and click Open to run it — double-clicking won’t work.

• Download SIP and PyQt5 from Riverbank Coputing

• Open a Terminal and use cd ~/Downloads to get to the download directory.

• Use tar xzvf sip-*.tar to extract SIP and cd sip-* to change into the SIP directory

• Run python3 configure.py, make and sudo make install.

• Use cd ~/Downloads to get back to the download directory.

• Use tar xvf PyQt-*.tar to extract PyQt and cd PyQt-* to change into the PyQt directory.

• Run sed -i -e "s/qmake_QT=\[webkit, network\]/qmake_QT=[webkit, network, printsupport]/" configure.py

• Run sed -i -e "s/qmake_QT=\[webkitwidgets\]/qmake_QT=[webkitwidgets, printsupport]/" configure.py

• Run python3 configure.py --qmake ~/Qt/5.3/clang_64/bin/qmake --sip /Library/Frameworks/Python.framework/Versions/3.4/bin/sip and accept the license.

• Run make and sudo make install.

• Run python3 setup.py install to install all other dependencies

Donating

Working on qutebrowser is a very rewarding hobby, but like (nearly) all hobbies it also costs some money. Namely I have to pay for the server and domain, and do occasional hardware upgrades ^[1].

If you want to give me a beer or a pizza back, I’m trying to make it as easy as possible for you to do so. If some other way would be easier for you, please get in touch!

• PayPal: me@the-compiler.org

• Bitcoin: 1PMzbcetAHfpxoXww8Bj5XqquHtVvMjJtE

Authors

Contributors, sorted by the number of commits in descending order:

• Florian Bruhin

• Claude

• rikn00

• Peter Vilim

Thanks / Similiar projects

Many projects with a similiar goal as qutebrowser exist:

• dwb (C, GTK+ with WebKit1, currently unmaintained - main inspiration for qutebrowser)

• vimb (C, GTK+ with WebKit1, active)

• vimprobable (C, GTK+ with WebKit1, active)

• surf (C, GTK+ with WebKit1, active)

• luakit (C/Lua, GTK+ with WebKit1, not very active)

• jumanji (C, GTK+ with WebKit1, not very active)

• uzbl (C, GTK+ with WebKit1/WebKit2, active)

• conkeror (Javascript, Emacs-like, XULRunner/Gecko, active)

• lispkit (quite new, lisp, GTK+ with WebKit, active)

• Vimperator (Firefox addon)

• Pentadactyl (Firefox addon)

• VimFx (Firefox addon)

• vimium (Chrome/Chromium addon)

Most of them were inspirations for qutebrowser in some way, thanks for that!

Thanks as well to the following projects and people for helping me with problems and helpful hints:

• eric5 / Detlev Offenbach

• devicenzo

• portix

• seir

• nitroxleecher

Also, thanks to:

• Everyone who had the patience to test qutebrowser before v0.1.

• Everyone triaging/fixing my bugs in the Qt bugtracker

• Everyone answering my questions on Stack Overflow and in IRC.

• All the projects which were a great help while developing qutebrowser.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

---

1. It turned out a 160 GB SSD is rather small - the VMs and custom Qt builds I use for testing/developing qutebrowser need about 100 GB of space