Configuring and running the luakit browser

14 replies [Last post]
Joined: 02/12/2015

Taking on a challenge by @SkedarKing, I installed the luakit browser this evening and configured it to run more like I would run abrowser. This is a very nice and capable browser, with a lot of media-playing capability and the ability to open a lot of javascript-heavy websites properly. It starts up for me using just about 100mb of memory, which is quite small. Of course, like most modern browsers accessing the modern web, it quickly becomes a memory hog once you start opening a bunch of websites.

Here's a few notes on configuration options and on useful keybindings. I'm putting this here for my future self to remember, and for anyone else who would like to try this amazing little browser and could benefit from any of this information.

1. blocking ads
First thing I noticed was that ads were not being blocked, which pains me greatly. I've rarely seen a single online ad anytime in the last 10 years, so to see them popping up all over the place is just nasty. The web that normal users deal with every day is just a horrifyingly bad and ugly place. Time to fix that up with some proper ad blocking on this puppy.

By default, the ability to block ads is actually ENABLED on luakit, which makes the process of actually blocking ads much simpler. Hit your key to open a web page on luakit - the small "o" key - and type in the following address: luakit://adblock/
You'll be brought to a page where you see that ad-blocking is "ENABLED" in luakit, but you'll notice that you don't have any ad-blocking filters listed. We'll go to the "EasyList" website and grab some ad-blocking and tracker-blocking and other filters and remedy that situation.

Point your browser to the EasyList website by hitting the "o" key and typing this url:
You might want to bookmark this website for future use - if so, hit your Shift-B key combo for bookmarks.
Once on the EasyList page, read the descriptions of the major filters and decide the ones that you want. You should be, at a minimum, downloading the EasyList itself, which is the top filter on the page. I download all the filters on this page, and only get rid of one if it's causing me trouble. With your mouse, right-click on the "View EasyList" link and select the "Download Linked File" option in the pop-up menu. Point the file browser to:
and drop the 'easylist.txt' file there. Now, restart the browser by closing with the :q key combo. When you start back up, go to a website that's normally heavy with ads, like just about any of your local news or weather websites. You should notice that the ads have disappeared, or are nearly all gone. Go back to the EasyList website and download some more of the ad-block filters to ~/.local/share/luakit/adblock/
Restart the browser by closing with :q - each time you re-open luakit, you will have more of these adblock filters you download enabled in your luakit://adblock/ page.

2. Changing the default search engine away from evil Google.
By default, luakit will probably be using Google as its browser. You can change this by going to the settings page. Type the settings address:
Search for the setting 'window.default_search_engine' by hitting the '/' key and typing 'window.default'. When you find that setting, you'll see a text box on the right hand side that says "default". Change that text box from "default" to "duckduckgo", making sure that you spell it just like I did, with all small letters.
Now search for something online by hitting the small "o" button and typing in your search term. You'll be searching it on duckduckgo instead of google.

3. Key bindings - lots and lots of key bindings.
luakit is a keyboard-centric browser. Some of what I wrote above about using the mouse is probably considered "neanderthal" thinking by veteran luakit users. But this is my first day and I'm still learning all the hundreds of key bindings.

In order to scroll through the keybindings, type
and hit the "Bindings" link. This will bring up a pretty thorough list for you to go through. If you are familiar with the vim key-bindings, you'll find that luakit uses a lot of vim key-bindings to to navigate around the page and so forth.

Here are some that I'm using a lot so far today:
small letter "o" for "open" - to open a web url. Or to search for a term online, just hit "o" and write your search term and hit Enter.
small letter "t" for "tabopen" - to open a new tab.
small letter "d" for closing a tab
"gg" to go to the top of a page, and Shift-G to go to the bottom.
Shift-h to go back a page, and Shift-l (small letter "L") to go forward.
:q to quit the browser.


That's all for now. I'll write about enabling noscript and doing some other stuff tomorrow when I have time.

Joined: 02/12/2015

luakit on Trisquel screenshot. It's available in the Software center on my Trisquel 10 beta.

Joined: 02/12/2015

luakit works the same on Trisquel. The version number on Trisquel 10 beta is 2.1-2, so it's a bit old. However, the web engine that luakit is based on is webkit2gtk, for which Trisquel 10 beta is running the most current version, 2.34.1. Most security related issues are going to involve webkit2gtk, so good job by Trisquel's devs in making sure Trisquel 10 is using the latest version.

One difference I've noticed with this version is that it's a little bit buggy - sometimes when I try to go to a new web page, luakit just shows me a blank page. If I hit the "r" key to reload the web page, then the page shows up properly.

Joined: 02/12/2015

Getting noscript running in luakit:

1. Edit the luakit configuration file and un-comment the line about 'requiring' noscript by opening it with your favorite text editor (I'll use the nano text editor here):
sudo nano /etc/xdg/luakit/rc.lua
Scroll down about 4-5 pages until you see a paragraph that begins with the line "NoScript plugin, toggle scripts and or plugins on a per-domain basis" (about line 148 in my config file). At the bottom of that noscript paragraph is a short line that says:
-- require "noscript"
Remove the two dashes and the single space at the beginning of that line to un-comment it, which will enable noscript on your system.
Note that the noscript paragraph also says this, which we will use later:
-- `,ts` to toggle scripts, `,tp` to toggle plugins, `,tr` to reset.

2. Save the changes to the configuration file. If you are using the nano text editor, hit Ctrl-o and hit the Enter key to accept changes and save, and then his the Ctrl-x key combination to exit.

3. Close luakit. If you have it open, you can close the entire program with ":q". Now restart luakit from your menu or by typing 'luakit' in your terminal browser.

4. Go to a website that wants to run a bunch of unecessary javascript. One that I'm familiar with is the GNU/Linux benchmark testing website,, which has lots of completely unecessary javascript. Now type the key combination ',ts' (comma t s) in order to turn off javascript for that website with noscript. You can also turn off any plugins (I'm assuming this refers to things like embedded video players, but I haven't read further on it yet) with ',tp, (comma t p). Hit the 'r' button to reload the page and show you the changes in how it looks without scripts or plugins. The website should now stay that way - if you visit again tomorrow, noscript should remember that is not allowed to run javascript or plugins.

5. If you find that turning off javascript and/or plugins has caused the website to be unusable and you want to reset noscript to its default settings for that page, type ',tr', and hit the 'r' key to reload the page and see how it looks with javascript and plugins allowed again.

That should be it. As far as I can tell, noscript on luakit does not allow fine-grained control like it does on abrowser. On abrowser I can decide to allow one piece of javascript and deny others. For example, I can allow the 'gitlab' javascript on but refuse to allow the google 'gstatic' or the 'vimeo' javascript on the same page. On luakit, it appears that my only option is to either allow all scripts or not to allow any scripts. So far, that hasn't caused me trouble. Most sites think they need a lot of javascript running, but in reality they really don't. Other sites, like, run their own simple and safe javascript, but don't use a bunch of google javascript spyware or other 3rd party javascript.

EDIT: In order to disable javascript and plugins by default, add a couple more lines to the 'noscript' section of the /etc/xdg/luakit/rc.lua config file discussed in step one above, so that the entire section looks like this:
-- NoScript plugin, toggle scripts and or plugins on a per-domain basis.
-- `,ts` to toggle scripts, `,tp` to toggle plugins, `,tr` to reset.
-- If you use this module, don't use any site-specific `enable_scripts` or
-- `enable_plugins` settings, as these will conflict.
require "noscript"
local noscript = require "noscript"
noscript.enable_scripts = false
noscript.enable_plugins = false

Then re-start luakit, and noscript will be disabling all js and plugins by default. You can enable them for the websites you want by using the ,ts toggle for scripts, and the ,tp toggle for plugins, and then refreshing your page with the letter "r". Return to default settings for disabling js and plugins with the ,tr toggle.

Joined: 02/12/2015

The luakit documentation recommends that the rc.lua config file be moved to the home directory and that any changes be implemented in that location instead of in /etc. So run the following command:
cp /etc/xdg/luakit/rc.lua ~/.config/luakit/

and make changes to ~/.config/luakit/rc.lua from now on.

Joined: 04/01/2021

That is just moving too fast for me. I'm afraid I'll need to cut one of my arms again soon and clone myself.

Joined: 11/01/2021

I dunno, I thought it looked fairly simple, I hope more people will support, luakit though. :)

Joined: 04/01/2021

I forgot to mention that I find it great that andyprough is ready to get out of his way to write reports from his own explorations and post them here. It is way more encouraging than when people just vaguely mention a name and say it's cool stuff.

Not every Trisquel user will want to go into installing hyperbola or luakit, but the step-by-step guides are very precious for those who would, time permitting.

Joined: 11/01/2021

Btw, press :

and then tab a few times, you will see some options for commands you can do.

I hope that shortcut helps people.

Joined: 02/12/2015

Oh wow, did not know that. This thing has so many options and features, it's a bit much to take in all at once, like @lanun was saying. I hope we are able to determine its relative level of security. If it's secure enough, I could be using it as my go-to browser for years to come. I love the keyboard-centric nature of it. And the ability to make changes to a config file and see them instantly come to life in the browser is very cool.

Joined: 11/01/2021

I wonder though, badwolf seems to leave less of a trail, when used, the only issue... is that adblocking on that is unknown to me... at this time,

up to you, what you do though...


Joined: 02/12/2015

Here's a couple of items for using luakit -

Clearing the cookies and cache:

1. go to the clear-data page in luakit:

2. Navigate up and down the list of sites at the bottom of the page, hit the Enter key to remove the data for one site. At the top of the list is "All" - hit Enter on that if you want to clear all cookies and cache from all sites.

Setting the User agent string:

1. Select a user agent string. This website has a bunch of the latest ones and doesn't require js to use it:
Copy the one you want to use.

2. go to the settings page in luakit:
Search (by using the / key) for "user agent". Paste your user agent string into the webview.user_agent box.

Joined: 02/12/2015

The 30 most useful keyboard shortcuts on luakit:
1. j - scroll page down a line
2. k - scroll page up a line
3. h - scroll page left
4. l - scroll page to the right
5. space - scroll down a full page
6. shift-space - scroll up a full page
7. gg - go to top of page
8. shift-g - go to bottom of page
9. [number]% - go to some percent of the page. Example - 50% - go to the halfway point of the page. 100% - go to the bottom of the page. 0% go to the top.
10. zi - zoom in
11. zo - zoom out
12. zz - reset zoom to default. If you put a number first, such as "150zz", then you will zoom that percent
13. shift-y - copy the current page's URL to the clipboard
14. shift-o - edit the current page's URL and go to the edited URL
15. o - open a URL
16. t - open a URL in a new page (t-Enter will open a new blank tab)
17. shift-t - open a URL based on the current page's URL in a new tab
18. shift-h - go back in browser history. "4-Shift-h" would go back 4 places in browser history
19. shift-l - go forward a spot in browser history. "4-Shift-l" would go forward 4 spots
20. shift-j - go to the next tab
21. shift-k - go to the previous tab
22. d - close the current tab
23. gh - open the home page
24. gy - duplicate th current tab
25. r - reload the page (shift-r - disregard the cache and reload the current page)
26. ctrl-c - stop loading the current tab
27. zq - quit without saving the session
28. zz - quit and save the session
29. shift-b - add a bookmark for the current page
30. gb - open the bookmarks manager

Joined: 04/23/2015


A couple of questions:
Re 'user agent,' any recommendations? I went with edge on Windows 10.

The folder we put the easylists in has a file named subscriptions already. I left it alone. What's that for?

I tested local news and it goes to 'web crash' and all tabs crash. That's the only one so far.

Re: cp /etc/xdg/luakit/rc.lua ~/.config/luakit/
How to translate that to a luakit installed via guix? I assume that's the reason why /etc/xdg/luakit/rc.lua doesn't exist for me.

I haven't enabled NoScript yet.

Joined: 02/12/2015

> Re: cp /etc/xdg/luakit/rc.lua ~/.config/luakit/
How to translate that to a luakit installed via guix? I assume that's the reason why /etc/xdg/luakit/rc.lua doesn't exist for me.

I talked about how to find rc.lua on Guix in this post -

Let me know if you still can't find it. I also use a small command line program called "fd" to find files on my system like rc.lua. fd is either "fd" or "fd-find" in most package managers I think:
fd -HI rc.lua /
fd can find any file on your system in seconds, very fast, and doesn't need to generate an index like 'locate'. -H is for searching hidden files and folders, and I don't remember what -I is for but I always use -HI and it works great.

>Re 'user agent,' any recommendations? I went with edge on Windows 10.

I just use Firefox on Linux as my user agent. If you want one that will display the web pages as accurately as possible, you could use one of the Safari user agents, since Safari and luakit use the same web engine. Although I haven't noticed any page rendering problems with the Firefox user agent.

>The folder we put the easylists in has a file named subscriptions already. I left it alone. What's that for?

It seems to tell luakit what lists you have in the folder. I'm pretty sure that if you deleted it and restarted luakit, luakit would just regenerate a new subscriptions file.