How to install qutebrowser on TrueOS / FreeBSD


qutebrowser ( is a lightweight browser with vim-like keybindings and userscript support. Before I discovered it, I found most other browsers that I tried to be bloated, slow, or poorly maintained and out-of-date. Now I rarely use any other browser.

Unfortunately, qutebrowser is not (yet) in the FreeBSD ports tree. I worked out how to install it, and thought I would share my notes here in case they are of use to someone else. If you want to try qutebrowser before going through the steps below, there are binary packages available for OpenBSD, OSX, Windows and many flavors of Linux (see

As noted below there are a couple of steps that take a while, but they can be unattended (ie, you can be doing something else). Overall it’s fairly easy once you know the steps. qutebrowser can run with with either a webkit or (not yet fully-featured) webengine backend, but because the latter requires PyQt5 5.7 or higher, these steps will give you a webkit-only browser until that FreeBSD port is upgraded.

(1) Get or update the ports tree:

replicate ports tree with git for TrueOS (see the FreeBSD Handbook if you’re using vanilla FreeBSD):

$ sudo git clone /usr/ports

Have a coffee. This is going to take a while.

if you already have the ports tree (again, for TrueOS only), then update it:

$ cd /usr/ports ; sudo git pull

(2) Install SIP from ports:

$ cd /usr/ports/devel/py-sip/ && sudo make PYTHON_VERSION=3.5 install clean
$ sudo ln -s /usr/local/bin/sip-3.5 /usr/local/bin/sip

(3) Install PyQt5 from ports:

$ cd /usr/ports/devel/py-qt5/ && sudo make config

IMPORTANT: make sure “demo” is de-selected in the dialog box that comes up, otherwise the build fails.

$ sudo make PYTHON_VERSION=3.5 BATCH=yes install clean

The “BATCH=yes” is optional, but it will avoid the build pausing many times to present you with an option. Just use this option if you are going to accept all the defaults anyway.

Have another coffee. This is going take a while. If you didn’t use “BATCH=yes” you’re going to have to click on quite a few dialog boxes.

(4) Use pip to install qutebrowser in an virtualenv:

$ sudo pkg install py27-virtualenv
$ sudo virtualenv --python=python3.5 /usr/local/virtualenvs/qutebrowser
$ sudo /usr/local/virtualenvs/qutebrowser/bin/pip install qutebrowser
$ sudo ln -s /usr/local/virtualenvs/qutebrowser/bin/qutebrowser /usr/local/bin/qutebrowser

(5) Create some necessary symbolic links:

$ sudo ln -s /usr/local/lib/python3.5/site-packages/PyQt5/ /usr/local/virtualenvs/qutebrowser/lib/python3.5/site-packages/
$ sudo ln -s /usr/local/lib/python3.5/site-packages/ /usr/local/virtualenvs/qutebrowser/lib/python3.5/site-packages/

(6) Copy the .desktop file from github:

$ curl -o /usr/local/share/applications/qutebrowser.desktop


Does it play full-screen videos on YouTube ?


I’d never tried doing this in qutebrowser, so I had to check. As i turns out, no QtWebKit-based browser will play fullscreen video within the browser itself. See this github issue for details:

However, you can easily play fullscreen video using mpv (presumably this will work with other video players such as vlc) and set up a single-key shortcut to launch a page’s video in mpv (or vlc, etc) as described in FAQ number 9 here:

I’ve also just tested fullscreen video in QtWebengine based qutebrowser (on MacOS) and fullscreen Youtube video works directly in the browser there. So as soon as the PyQt5 FreeBSD port gets updated to 5.7 this should work on qutebrowser in FreeBSD too.