[opensourcedex]

luakit is a free, open source browsers & extensions project written in Lua and released under GPL-3.0. It has 2,315 GitHub stars, 254 forks and 253 open issues, and was last pushed 4 months ago. On this registry it ranks #57 of 65 tracked projects in Browsers & Extensions, with 5 head-to-head comparisons available. It gained 3 stars over the last 3 tracked days.

What is luakit?

What it is

Luakit is a fast, small, and simple micro-browser framework built around the WebKit web content engine and the GTK+ toolkit. It is extensible by Lua, so browser behavior and user workflows can be shaped through Lua configuration files instead of only through fixed settings screens.

It solves a concrete problem in the Linux and BSD desktop browser ecosystem: users who want keyboard-driven browsing like vim-browser, jumanji, Vimium, or cVim, but also want a standalone browser that can be customized programmatically. Luakit provides vim-like bindings out of the box and a Lua configuration model for tuning the browser without becoming a full browser developer.

Key capabilities

  • Luakit uses the WebKit engine for web pages and the GTK+ 3 toolkit for its desktop interface, making it a standalone browser framework rather than an extension inside another browser.
  • It supports vim-like keyboard bindings for users familiar with quitebrowser, vim-browser, jumanji, Vimium, or cVim.
  • Configuration files are written in Lua, so users can program settings, modules, fonts, colors, and browser behavior.
  • It offers three customization paths: in-browser :settings for WebKit options, userconf.lua for user overrides, and copied rc.lua for deeper local control.
  • It uses LuaJIT by default or plain Lua 5.1, and depends on lfs, webkit2gtk, sqlite3, gstreamer, and lua-socket for file access, web content, database support, video playback, and gopher support.
  • It includes debugging aids such as --log, the :log console, and :lua for running Lua code at runtime.

Who uses it and how

  • Linux and BSD users install luakit from package managers such as apt-get, pacman, emerge, guix, pkg, pkg_add, or xbps-install and run it as a daily browser.
  • Keyboard-first users adopt it when they want vim-like navigation without relying on extensions inside a larger browser.
  • Power users copy theme.lua, userconf.lua, or rc.lua into their home configuration directory to change colors, fonts, key behavior, and modules.
  • Developers and packagers clone the repository, build with make, run make test, and use DEVELOPMENT_PATHS=1 to start from the build directory with local files.
  • Troubleshooting users enable debug output with luakit --log=verbose or module-specific logs and inspect messages through :log.

Getting started

Install luakit from your distribution or BSD package manager, or build it from source with git clone, make, and sudo make install. Start it with luakit [URI..], then open :help or :settings.

When to use it — and when not to

Use luakit when you want a small Lua-extensible WebKit browser on Linux or BSD and can manage dependencies such as GTK+ 3, Lua or LuaJIT, lfs, webkit2gtk, sqlite3, gstreamer, and lua-socket. Avoid it if you need a browser with no local configuration work, because copied rc.lua files may need manual adaptation after updates. The 253 open issues and missing contributor count suggest a community-maintained project that may require self-service debugging.

project readme (upstream, from github) — read inline

Luakit

luakit is a fast, light and simple to use micro-browser framework extensible by Lua using the WebKit web content engine and the GTK+ toolkit.

Don't Panic!

You don't have to be a developer to use luakit on a daily basis. If you are familiar with quitebrowser, vim-browser, jumanji or extensions like Vimium or cVim etc, you will find luakit behaves similarly out of the box.

Requirements

  • GTK+ 3
  • Lua 5.1 or LuaJIT 2
  • lfs (lua file system)
  • webkit2gtk
  • sqlite3
  • gstreamer (for video playback)
  • lua-socket (for gopher support)

Installing

Luakit is available on most Linux Distributions and BSD system via their package managers. A few examples below:

  • Debian/Ubuntu: apt-get install luakit
  • Gentoo: emerge luakit
  • Guix: guix install luakit
  • Arch: pacman -S luakit
  • FreeBSD: pkg install luakit
  • OpenBSD: pkg_add luakit
  • Void Linux: xbps-install luakit

Packaging status:

Packaging Status

Installing from source

Make sure you system fulfills the requirements listed above, then install luakit with the following commands:

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

Uninstall with:

$ sudo make uninstall

Note: If you are on BSD, you might need to use gmake.

Use Luakit

Just run:

$ luakit [URI..]

Or to see the full list of luakit launch options run:

$ luakit -h

Luakit works with vim-style bindings. To find out more, type :help within luakit.

Configuration

Luakit configuration files are written in lua. This means you can program within the config files, which make the configuration options endless.

There are three ways to customize luakit.

1. within luakit

After starting luakit, type :settings. This page shows you webkit engine related settings.

2. userconf.lua

Create a file called $HOME/.config/luakit/userconf.lua. Then add your configuration there. Configuration in this file supersedes configuration set in :settings

3. copy rc.lua

The most powerful customization is to copy rc.lua from /etc/xdg/luakit/rc.lua to $HOME/.config/luakit/rc.lua

When this file is found, /etc/xdg/luakit/rc.lua is ignored.

Be informed that when luakit is updated, you may need to adapt changes from /etc/xdg/luakit/rc.lua to your own copy.

Colors and fonts

Copy the /etc/xdg/luakit/theme.lua to $HOME/.config/luakit/theme.lua. You can change fonts and colors there.

Development Information

This section contains information about the compile and testing process.

Luakit honors the PREFIX variable. The default is /usr/local.

$ make PREFIX=/usr
$ sudo make PREFIX=/usr install

Notes:

  • You also have to set the PREFIX when uninstalling.
  • If you want to change PREFIX after a previous build, you need to make clean first.

Luakit uses luajit by default, to use lua you can turn off luajit with:

$ make USE_LUAJIT=0

To build with local paths (interesting for package maintainer and contributers). You may wish to build luakit with:

$ make DEVELOPMENT_PATHS=1

This lets you start luakit from the build directory, using the config and libraries within the same.

Take a look at config.mk for more options.

If you made changes and want to know if luakit is still working properly, you can execute the test suite with:

$ make test

Debugging Luakit

Enable debug output

Debug output can be turned on by starting luakit with the --log option.

$ luakit --log=verbose              # or: -v
$ luakit --log=all=debug            # or: --log=debug
$ luakit --log=lua/adblock=debug    # turn on debug on for the adblock module.

Console output an also be seen within luakit using :log when the log_chrome module is loaded (default). Note that debug log level may lead to a race condition when the update of the log page leads to debug output, which causes an update of the :log page.

Execute lua within Luakit

If you want to examine the lua state at runtime, you can do so by running lua script within luakit. This will print "Hello World!" on the console.

:lua print("Hello World!");

w:notify() can be used to show the output in the input/status bar. This example shows the configuration directory in the input/status bar.

:lua w:notify(luakit.config_dir)

Print the lua package search paths:

:lua w:notify(package.path:gsub(";","\n"))

To extend the lua debugging capabilities, you can copy "inspect.lua" from here into the luakit configuration directory. Now you can inspect complex data types like tables:

:lua local inspect = require "inspect"; w:notify(inspect(webview))

Tips and Fixes:

Video playback

If you're having issues with video playback, this is often related to buggy graphic drivers. It often helps to set LIBGL_DRI3_DISABLE before starting luakit:

$ export LIBGL_DRI3_DISABLE=1

HiDPI Monitor Configuration

If you have a HiDPI monitor (> 1920x1080) and find that web pages are too small, you can change the webview.zoom_level on the settings page (luakit://settings/) to 150 or 200 as per your taste.

Reporting Bugs

Please note that most rendering related issues come from the used webkit engine and can not be fixed by luakit. If you think your issue is luakit related, please use the bug tracker at:

https://github.com/luakit/luakit/issues

Coming from a very old luakit version? Look at the MIGRATION document.

IRC

Join us in #luakit on the irc.oftc.net network.

Frequently asked questions

Is luakit free to use?

luakit is open source under the GPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does luakit do?

Fast, small, webkit based browser framework extensible by Lua.

What is luakit written in?

luakit is primarily written in Lua. Its source is publicly available at https://github.com/luakit/luakit, and it has 2,315 GitHub stars.