Quick-start Guide

Using Luakit

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.

Just run:

luakit [URI..]

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

luakit -h

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 documentation.

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 <Enter>.

To switch to command mode, press : (i.e. <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 :; so :open means to first press :, and then type open.

Go to a URL in the current tab

Type :open followed by a space and the URL to navigate to, and press <Enter>. For example, to open the luakit website, type :open luakit.github.io and then press press <Enter>.

Shortcut: press o to switch to command mode with open already typed.


Press /, and type your search query, e.g: /luakit. Press <Enter> to finish typing your search query and switch back to normal mode. While in normal mode with highlighted search results, press n to 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:

  1. Run :tabopen luakit.org, and wait until the page finishes loading.
  2. Press d, and the new tab will close.
  3. Press 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.
  • The h, j, k, l, gg, and G key bindings all scroll in a vim-like manner.
  • The <Control-e>, <Control-y>, <Control-d>, <Control-u>, <Control-f>, and <Control-b> keys all scroll vertically by various amounts.


  • Press B to bookmark the current page.
  • Press gb or gB to open the bookmarks page in the current tab or a new tab, respectively.


It is possible to configure most of the global Luakit settings in the luakit://settings page. For further adjustments (per-domain settings, adjusting/defining bindings or commands) you should create a custom configuration file.

Beginning a custom configuration

To customize luakit, you can define your own configuration by creating a userconf.lua file in the ~/.config/luakit/ directory. This file is loaded automatically by luakit, if it exists. Any changes made to it will take effect after restarting luakit.

Changing key bindings

To add/remove key bindings, use add_binds and remove_binds methods from the modes module to do so. For example, the following code re-binds <Control-c> so the selected text gets copied to the clipboard:

--- userconf.lua

local modes = require "modes"

modes.add_binds("normal", {{
    "Copy selected text.",
    function ()
        luakit.selection.clipboard = luakit.selection.primary

If you just want to re-map an existing action to a new keybinding, you can use the remap_binds method. For example:

-- maps "<Control-p>" to the same action as "gT" (go to previous tab), and
-- keeps "gT" binded as well
modes.remap_binds("normal", {
    {"<Control-p>", "gT", true}

You can also check all the currently available key bindings in the luakit://binds page, for each of luakit's modes, along with their documentation and links to the exact location where they were defined.

Changing the theme

Apart from rc.lua, the other configuration file is theme.lua, which specifies the fonts and colours used by the interface widgets.

Location of configuration files

When looking for a .lua file by name, luakit checks the following locations, in the order specified here:

  1. The current directory.
  2. System directories for Lua files.
  3. Luakit's collection of included modules (/usr/share/luakit/lib/).
  4. The user's personal luakit configuration directory (~/.config/luakit/).
  5. The system configuration directories (/etc/xdg/luakit/).

To list the directories luakit will search when loading modules, run the following command:

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