Building surf browser (by suckless) on Debian/Ubuntu. Add media streaming support and fix some problems

Modern browsers require significant computer power and memory. They support various features, like account synchronyzation, adverts, browser appearance customization and others. Also their engines support a huge number of technologies and add-ons (like WebGL, Java), which affects the system performance (when things simpler and smaller they are faster). All these extra features is not really necessary.

There are suckless project, whose developers create simple and fast tools with minimum of code but wide flexibility. Their most popular achievements are dwm (window manager), st (terminal emulator), dmenu and surf.

In this article we will talk about surf browser. It is really lightweight browser with ~3000 lines in source code (exclude WebKit/GTK+, which is the engine). For example, Firefox has 20 million of them.

Surf supports Java, JavaScript, WebGL, custom styling (even for certain web pages), disk cache (can be redirected to RAM), webcam and microphone access, video and audio streaming (full Youtube support if all the necessary packages installed, we will talk about it below). All these things can be enabled and disabled. Also there is a feature to allow or disallow cookies and javascript for specific web pages.

Install tools to source code download

Let’s start.

First, we need tools to download source code from suckless official repository:

sudo apt install --no-install-recommends git ca-certificates

Source code download and building

Then we can download surf browser sources:

cd /tmp
git clone
cd surf/

If you try to compile it now, the error message will appear:

libsurf-webext.c:6:10: fatal error: gio/gio.h: No such file or directory
 #include <gio/gio.h>

To build surf browser, additional packages must to be installed in the system. They include tools, header files and libraries for developers.

We can install them by the following command:

sudo apt install --no-install-recommends build-essential libgtk-3-dev libgcr-3-dev libwebkit2gtk-4.0-dev

You can delete these packages later when you finish setting up and building the browser.

Now it is possible to build surf browser. Perform sudo make install clean:

sudo make install clean

Surf browser is installed in the system.

It’s time to test it, run the browser:

surf   ## See about it below

Try to use Ctrl+G shortcut (here you can write webpage address directly, for example,

surf-setprop: xprop: not found

If you have the following message appeared in your terminal (when using Ctrl+G or Ctrl+F):

surf-setprop: 1: surf-setprop: xprop: not found

Then you need to install xprop, it is presented in x11-utils package:

sudo apt install --no-install-recommends x11-utils

Now Ctrl+G and Ctrl+F (search on the page) shortcuts will work fine.


Press Ctrl+G then type "" and press [Enter]

If you hit the page, then it works.

Surf browser uninstalling

To uninstall surf from the system use sudo make uninstall in the directory with source code:

sudo make uninstall
rm -f /usr/local/bin/surf
rm -f /usr/local/share/man/man1/surf.1
rm -f /usr/local/lib/surf/
rmdir /usr/local/lib/surf

Add media streaming support (and full youtube support)

If you try to hit youtube and open any video:


You will see an error message on the video previews. Something like “HTML5 video is not supported”.

To add media streaming support additional (gstreamer) plugins are required. Also there is a way to open all the videos using mpv (see about it later).

For video support inside surf browser itself install these packages:

sudo apt install gstreamer1.0-libav gstreamer1.0-plugins-good

If you have the warning message appeared in the terminal when playing a video:

** (WebKitWebProcess:18743): WARNING **: 09:50:45.269: WebKit wasn't able to find the GStreamer opengl plugin. Hardware-accelerated zero-copy video rendering can't be enabled without this plugin.

You can insall OpenGL plugin:

sudo apt install gstreamer1.0-gl

This will add hardware acceleration support for video decoding (and reduce CPU usage). This is recommended if you have video card drivers installed.

Surf browser with full YouTube support + hardware acceleration (if video driver supports)

There is no sound when watching a video?

Install a plugin for your sound system (ALSA or PulseAudio):

sudo apt install --no-install-recommends gstreamer1.0-alsa
sudo apt install --no-install-recommends gstreamer1.0-pulseaudio

Now there should be full support for YouTube and other media resources:

surf   ## Some resources should be used with https:// to force encrypted connection (they don't have HTTPS redirect in their rules).

Note, that using HTTPS is very important. Especially when important information is being transferred (passwords, authorization keys, cookies, etc.).