luakit: a WebKit2GTK browser where all behavior is programmable in Lua

WebKit2GTK, LuaJIT and GTK+3: the three runtimes luakit links together

Two runtimes do almost all the work in luakit. WebKit2GTK handles page rendering, JavaScript execution and network requests, while LuaJIT handles browser behavior: keybindings, tab management, the download manager, adblocking and any extension you write. These two halves communicate through a Lua API that lets extensions reach into the WebKit layer without writing C code, which keeps the C core small.

GTK+ 3 is the windowing toolkit. The full dependency list from the documentation is: GTK+ 3, Lua 5.1 or LuaJIT 2, lfs (lua file system), webkit2gtk, sqlite3, gstreamer (for video playback) and lua-socket (for gopher support). Gstreamer and lua-socket are tied to specific features: their absence disables only video and gopher respectively, leaving the rest of the browser intact.

LuaJIT is the default at build time. Passing USE_LUAJIT=0 to make switches the runtime to standard Lua 5.1:

make USE_LUAJIT=0

No documentation explains when you would prefer Lua 5.1 over LuaJIT in practice.

Installing from package managers on most Linux distributions, and from source with make

The project installs via package managers on most Linux distributions and on FreeBSD, OpenBSD and other systems. The documentation gives these examples:

apt-get install luakit
emerge luakit
guix install luakit
pacman -S luakit
pkg install luakit
xbps-install luakit

Those commands cover Debian and Ubuntu, Gentoo, Guix, Arch, FreeBSD and Void Linux. For OpenBSD, the command is pkg_add luakit. For a source build, the sequence is:

git clone https://github.com/luakit/luakit.git
cd luakit
make
sudo make install

BSD users may need gmake instead of make. The default install PREFIX is /usr/local. To change it, pass the PREFIX variable to both make and the install step, and note that changing PREFIX after a previous build requires running make clean first, otherwise object files from the prior configuration remain. To run the test suite before installing:

make test

Three configuration layers and the order in which they supersede each other

Configuration in luakit has three distinct layers with a clear override order. The first is the :settings page, opened by typing :settings inside the browser. It exposes WebKit engine settings and writes them persistently without touching any file on disk.

The second layer is $HOME/.config/luakit/userconf.lua. Any Lua placed in that file runs on top of the built-in defaults and supersedes whatever was set through :settings. This is the appropriate layer for targeted adjustments: rebinding a single key, setting a download directory, or adding a site-specific rule.

The third layer, and the most comprehensive, is a full copy of /etc/xdg/luakit/rc.lua placed at $HOME/.config/luakit/rc.lua. When that file exists, the system-level rc.lua is ignored entirely. Every module load, keybinding and default behavior falls under your control. Visual appearance is handled through a parallel file: copy /etc/xdg/luakit/theme.lua to $HOME/.config/luakit/theme.lua to change fonts and colors. To start luakit from a local build directory during development, pass the DEVELOPMENT_PATHS flag:

make DEVELOPMENT_PATHS=1

Copying rc.lua transfers the upgrade burden to you permanently

The trade-off in choosing the rc.lua copy approach is stated plainly in the README: when luakit is updated, you may need to adapt changes from /etc/xdg/luakit/rc.lua to your own copy. Those changes do not arrive automatically through a package update. After each luakit upgrade, comparing your $HOME/.config/luakit/rc.lua against the new system default is the only way to discover what changed and which parts matter for your configuration.

The documentation gives no information about how often rc.lua changes between versions, which sections are most subject to change, or how to diff the two files efficiently. MIGRATE.md at the repository root addresses users coming from very old versions, but for routine upgrades between recent versions, the documented path is a manual comparison. The userconf.lua approach avoids this burden by sitting on top of the system defaults rather than replacing them, but it cannot override module loading order or other behaviors that rc.lua controls before userconf.lua is processed.

Theme files work the same way. Copy /etc/xdg/luakit/theme.lua to your config directory and edit fonts and colors there. Changes to that file affect only the visual layer, and browser behavior is not tied to it.

The --log flag, the :log race condition, and live Lua evaluation with :lua

Luakit provides three debug tools. The first is the --log flag at launch, which sets the log verbosity for the session:

luakit --log=verbose
luakit --log=all=debug
luakit --log=lua/adblock=debug

The module-specific form lets you scope log output to a single subsystem. The second tool is :log inside the browser, which requires the log_chrome module and is loaded by default. The README documents a known failure mode here: running at debug log level can produce a race condition where updating the :log page itself generates debug output, which then triggers another update of the :log page. This feedback loop makes :log unreliable at debug level, and the README notes it explicitly.

The third tool is :lua, which evaluates Lua expressions in the current browser context:

:lua print("Hello World!");
:lua w:notify(luakit.config_dir)
:lua w:notify(package.path:gsub(";","\n"))

The w:notify() call routes output to the status bar rather than the console, which is useful when the terminal window is not visible. For inspecting complex data like tables, the README points to inspect.lua from a separate third-party repository, which you copy into the luakit configuration directory to make require available.

Video playback failures on some drivers, and the HiDPI zoom level at luakit://settings/

Two known issues in the documentation have workarounds. Video playback failures on certain machines trace to graphic drivers rather than to luakit or WebKit. The fix is to set an environment variable before starting the browser:

export LIBGL_DRI3_DISABLE=1

The README says this helps for buggy driver cases without listing which drivers are affected.

For HiDPI monitors above 1920x1080, pages can appear too small. The fix is to change the webview.zoom_level on the settings page at luakit://settings/, where 150 and 200 are the two example values the README gives. The setting is stored independently of any config file, so it persists across sessions without requiring an edit to userconf.lua or rc.lua. Both workarounds address hardware and driver configuration rather than anything in luakit's code.

Rendering issues belong to WebKit, and when luakit is the wrong browser to reach for

Luakit runs on Linux and BSD systems only, and the toolkit dependencies GTK+ 3 and webkit2gtk are not available on Windows or macOS. Anyone who needs to work across operating systems has no supported path.

Rendering is a second hard boundary. Most display-related bugs in luakit trace back to the webkit2gtk version shipped by your distribution, not to luakit itself. The README makes this explicit: most rendering-related issues come from the WebKit engine and cannot be fixed by luakit. Before filing an issue on the luakit tracker, determine whether the behavior also appears in another WebKit-based browser on the same system.

For users who want vim-style keybindings without adopting a separate browser, the README names Vimium and cVim as browser extensions that deliver a similar keyboard model inside Chrome or Firefox. The README also names qutebrowser and jumanji alongside luakit as standalone browsers with a similar interaction model, for anyone comparing alternatives in that category.

Editorial conclusion

luakit suits users on Linux who want a keyboard-driven browser scriptable in Lua and who are prepared to maintain their own rc.lua copy through upgrades. Type :help inside the browser to verify that the vim-style model works for you before committing. Skip it if you need Windows or macOS support, a GUI settings panel, or a browser where the vendor handles rendering bugs. Most rendering failures come from WebKit rather than from luakit itself. Before copying rc.lua, compare it against /etc/xdg/luakit/rc.lua to understand the manual merge work each future upgrade requires.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. luakit/luakit on GitHub
3. Project website
4. README
5. Releases