Skip to content
Go to file

Latest commit


Failed to load latest commit information.
Latest commit message
Commit time


webmacs is yet another browser for keyboard-based web navigation.

It mainly target emacs-like navigation, and started as a clone (in terms of features) of conkeror.

See the documentation manual:

webmacs is based on qt webengine and written mainly in Python (version 3).


Short list of features:

Installation (… and development)

There are two recommended ways of installing webmacs:

  1. Nix
  2. pip/virtualenv


Currently, the easiest way to install webmacs is via the Nix package manager:

nix-env -i webmacs

Need more help with nix?

Nix is available for Linux, macOS and other Unix-like systems. Rest assured that removing Nix (along with any packages installed using Nix) is as easy as rm /nix -rf.

If you do not have Nix, install it. For details see, but this step approximates to

bash <(curl

and will require you to provide a sudo password.

Look out for, and follow the instructions which will appear once nix is installed, and which will look something like this:

Installation finished!  To ensure that the necessary environment
variables are set, either log in again, or type

  . /home/yourusername/.nix-profile/etc/profile.d/

in your shell.

If you don’t spot this, the installation will appear to have failed.

Now you can use nix-env to install webmacs:

nix-env -i webmacs

For further details, see

working on webmacs with nix

The command

nix-shell -p webmacs

will drop you into a shell which makes available all the compilers and libraries required to build and run webmacs, thus nix-shell plays the role of virtualenv in the pip/virtualenv approach described below. Unfortunately, some of the libraries required to run the tests, are not yet available in this shell.


If you do not want to or cannot use nix, then use pip/virtualenv - be prepared to have a working c and c++ compiler with python development library. Note I only have tested on linux.

You will also need the PyQt5 library, as I believe it can’t be installed through pip. It’s easy to install using any package manager though.

Then you have to check out the repository (do not forget the recursive flag):

git clone --recursive

To test it, or work on it, I recommend virtualenv:

virtualenv --system-site-packages -p python3 venv
# activate the virtualenv
source venv/bin/activate
# install webmacs in there
pip install -e <path_to_webmacs_sources>
# and now to run webmacs
python -m webmacs.main

Then you can create a system alias to run it:

sudo ln -s <path_to_venv>/bin/webmacs /usr/local/bin/webmacs
# now you can use the webmacs command on your system, given that
# /usr/local/bin is in your PATH.

Running tests

To run the tests, you will need a few more dependencies (the virtualenv needs to be activated):

# install test dependencies
pip install -r <path_to_webmacs_sources>/test-requirements.txt
# also install the herbstluftwm window manager, using your package manager.
# Example on fedora:
sudo dnf install herbstluftwm

Then you can run the tests (the virtualenv needs to be activated):

py.test <path_to_webmacs_sources>/tests
# you can run them with the windows visible:
py.test <path_to_webmacs_sources>/tests --no-xvfb

Qt versions support

Every stable Qt version from (and including) 5.7 should work with webmacs.

Note that there are some known limitations:

  • spell checking only works with Qt >= 5.8
  • support for iframes is broken with Qt < 5.10 (webcontent-edit mode is unreachable)
  • dev tools only works with Qt >= 5.11


Contributions are much welcome! Writing this browser is exciting and I love that, though I don’t have many time to spend on it, having a family life and a job; And anyway the more we are to work on it and use the tool, the better!

You can’t perform that action at this time.