If you've used browsers like vimperator, or vimium, you'll find yourself right at home; most if not all luakit actions are available via keyboard commands.
Or to see the full list of luakit launch options run:
Opening the help page
To open the internal help page, press
<F1>. From there, you can open
the introspector to view current keybindings or open the included API
Switching to command mode
Many common operations in luakit, such as typing and opening a URL, involve the
use of commands. This is done by switching to command mode, typing the
command, and pressing
To switch to command mode, press
<Shift-;>), and the command
bar will appear at the bottom of the window. In the remainder of this document,
commands will be written prefixed by a
:open means to first press
:, and then type
Go to a URL in the current tab
:open followed by a space and the URL to navigate to, and press
For example, to open the luakit website, type
:open luakit.github.io and then
o to switch to command mode with
open already typed.
/, and type your search query, e.g:
to finish typing your search query and switch back to normal mode.
While in normal mode with highlighted search results, press
jump to the next search result, and
N to jump to the previous one.
Opening, closing, and undo-closing tabs
Try the following steps in order:
:tabopen luakit.org, and wait until the page finishes loading.
d, and the new tab will close.
u, and the just-closed tab will reappear.
Scrolling in a web page
There are several different keys to scroll a webview:
- The arrow, page up/down, and home/end keys all work as one would expect.
Gkey bindings all scroll in a vim-like manner.
<Control-b>keys all scroll vertically by various amounts.
Bto bookmark the current page.
gBto open the bookmarks page in the current tab or a new tab, respectively.
Beginning a custom configuration
Luakit loads only one configuration file:
rc.lua; that's the entry
point for loading all the other configuration files and modules one might need,
which are all written in Lua.
Any configuration file can load ("require") another Lua configuration file by
specifying its name. When looking for a
.lua file by name, luakit
checks the following locations, in the order specified here:
- The current directory.
- System directories for Lua files.
- Luakit's collection of included modules (
- The user's personal luakit configuration directory (
- The system configuration directories (
When launching luakit after a fresh install, it will look for the file
rc.lua in these directories in order. If there is no such file in the
personal luakit configuration directory, luakit will fall back to the
To list the directories luakit will search when loading modules, run the following command:
To customize luakit, we can define our own configuration by creating a
rc.lua file in the
/home/$USER/.config/luakit/ directory. The easiest
way of creating a proper functional configuration is copying the global
mkdir -p ~/.config/luakit/ cp /etc/xdg/luakit/rc.lua ~/.config/luakit/
Now we can modify the configuration file, and any changes will take effect
after restarting luakit. The official
rc.lua file might be changed in
future releases, however, and if we modify our copy
extensively, it may be difficult to merge any changes to the configuration
file into our setup. One way of minimizing the impact of future upgrades
is to add only a single line like the following to our personal copy of
This should be added just before the end of the "User script loading" section.
Now we can create a new file,
where we can introduce all the changes we want; these changes will not have to
be merged with any future changes to the
Changing the theme
rc.lua, the other configuration file is
specifies the fonts and colours used by the interface widgets.