A basic introduction to qutebrowser


A basic introduction to qutebrowser

qutebrowser is a highly customizable, keyboard driven, open source web browser.
You can use qb like a regular browser with a mouse (and with most of the usual keyboard controls).
However once you are familiar with it, it is rarely if ever faster to use a mouse for a given action.
This makes it at least tangentially relevant to a keyboard forum.

qb uses QtWebEngine.
While qb is not exactly an alternate front end for google chrome you can probably think of it as that if your so inclined.
- QtWebEngine is based on Google’s Chromium.​
- Chromium is an open-source browser project that forms the basis for the Chrome web browser.​
- QtWebEngine backports security fixes from latest Chromium versions.​
qb is a mature and healthy open source project with regular commits/updates. - github

There are many ways to use qb as well as extensive docs - this is just a basic overview of the functions I use regularly as an entry point.
(A cheat sheet of keyboard commands can be found here)
If you've never used vim before some of the commands my seem a little esoteric however they do combine nicely and you can of course customize them easily.

Clicking on a text field or pressing i will put you in insert mode (indicated with a green bar at bottom of browser), press escape to return to normal mode.

j/k - scroll up and down (generally I use Ctrl+j/Ctrl+k which is an altered bind shown below which scrolls slightly further)
H/L - back and forward

f - link hints (type the hint to follow the link) (also used to select text fields placing into insert mode)
F - same as above but in new tab (akin to right clicking and selecting 'open in new tab')

J/K - next/previous tab (you may want to reverse these)

o - open website by fuzzy finding through history/bookmarks
O - as above but will open in new tab

gt - show tab buffer (start typing to fuzzy find by tab title or select by number)
d - close tab
u - undo closing tab
g$ - show last tab
g^ - show first tab
<n>gm - pass a number to tab-move -eg. pressing 15gm would move the current tab to position 15
gl - move current tab left
gr - move current tab right

gg - scroll top
G - scroll bottom

Entering text and pressing return in the 'open' buffer will use it as a search term as in most browsers when typing into the url field.
Instead of using the default search engine (DuckDuckGo initially but is a user setting) you can map search engines to identifiers
so for eg. typing "yt buckling spring" will open a youtube search for "buckling spring" (shown with other settings below.)

Alternatively DuckDuckGo has the concept of bangs(!'s) which can be used instead of mapping your own in qb:
so for eg. pressing o + !g test will search google with the term "test" (with ddg still set as defualt search engine)
some other ddg bangs:​
!w - wikipedia​
!wa - wolfram alphra​
!gi - google images​
!gm - google maps​
!yt - youtube​
!b - bing​
!a - amazon​
!e - ebay​

gi - selects first input (used for quickly entering insert mode in a websites main search field [google, youtube ect.])

/ - search(find)
press enter to finalise search term​
n - go to next instance​
N - go to previous instance​
(pressing enter again follows if link)​
Pressing Esc exits the search​
selecting/copying arbitrary text:
use search for a substring at the beginning of the text you wish to copy​
(press enter to finalise search term)​
v - enter caret mode​
use w and b to increase and decrease selection by word​
use y to copy(yank) text - (Ctrl-c will also work)​
common use would be to then press o or O and paste as a search term​

go - edit current url
yy - copy(yank) current url
;y - use hints to copy(yank) url in page

Setting Changes
Typing :set (enter) will take you to an interactive settings page
(use search like you would in any other webpage to navigate)

eg. from the settings page type /session.la (enter) - to find the session.lazy_restore entry
press tab to enter that value field​
press i to enter insert mode​
change the setting to true
press esc to exit insert mode​

Or you can manually change settings from the commandline (pressing : enters the commandline)

eg. type :set ses to fuzzy find the session.lazy_restore setting
tab down to the entry​
press space
tab through the options for that setting​
press enter to select​

Typing :version (enter) will take you to the version info page - under paths you can find the config folder which contains your autoconfig.yml
- which contains any user settings you have altered for backup

Potential changes to make initially
pin the cheatsheet as the first tab

scrolling.bar true
auto_save.session true
session.lazy_restore true - when browser is first opened do not load pages from last session until tab is selected
tabs.select_on_remove prev - after closing a tab with d return to the prev tab (this will be the one you were on initially if a website pop-up opens a new tab and you instantly close it with d)

url.searchengines {"DEFAULT": "https://duckduckgo.com/?q={}", "g": "https://www.google.com/search?hl=en&q={}", "gi": "google.com#q={}&tbm=isch", "yt": "https://www.youtube.com/search?hl=en&q={}"}
- Mapping search engine identifiers as mentioned previously​

qb uses a basic monospace font by default (the first match it finds from the list in the value for fonts.monospace)
(You can change all the fonts that are set to monospace by altering this entry)​
You will likely have to increase the point size for some of the font entries.
The following are some good candidates to change the overall aesthetic of the browser:
- fonts.completion.entry
- fonts.completion.category
- fonts.hints
- fonts.statusbar
- fonts.tabs

There are some aesthetic setting changes that have been packaged as themes. I would recommend either looking at the settings they change and manually altering them to your taste or backing up your autoconfig.yml before following the theme creators installation instructions.

Type :bind (enter) for a list of current binds
Type :bind (space) and paste the following to use
<Ctrl+j>: scroll-px 0 100​
<Ctrl+k>: scroll-px 0 -100​
- it is useful to have something in-between the amount scrolled by j/k and Ctrl+f/Ctrl+b
- this also fixes an issue with the way some websites take over the function of a up/down arrow press causing j/k not to work (eg. youtube)​

Finding more
Use the cheatsheat of default bindings

A lot of answers can be found by using the fuzzy find from the command line
eg. How do I pin a tab?
Try typing :pin and tab through the options​

Type :help (enter) to go to main page of docs
or type :help (space) to fuzzy find commands/settings and press enter to go to relivent part of the docs​

Google/IRC/reddit ect.

mp4 videos
This is one of the two main caveats against using qb.

The version of qtwebengine that qb is built against doesn't have support for decoding mp4 videos as they contain propriety codecs.
Many websites now use html5 video, but you will still encounter mp4.
(for eg. If your watching a video soon after it has been uploaded/streamed to youtube it will not play in the browser until it is transcoded)​
- I don't find this to be a problem as I was already playing web video through a media player as it allows you to cache and skip through the videos properly and I find frame rate smoother.

You could build qtwebengine with the propriety codec flag turned on yourself - However doing so is not a trivial process.
(There is a flatpack for qb built against this if your using linux, however I've not personally tested it)

I use a small script for the main websites I visit where mp4 is used that spawns the video in mpv player when I copy the url (twitch, vimeo etc.)
Some gif containers use mp4 for which I use the bind below to spawn mpv in the top right corner in repeat mode
- W: hint links spawn mpv --ontop --loop --geometry=100%:0% {hint-url}
- (you will need mpv player in your os's path)​

You can manually find the direct video url by opening web inspector (wi), clicking play on the video, typing mp4 into the search field of the web inspector and using mpv (or vlc etc.) to open the link
- I rarely have to do this.​

Ad Blocking/Plugins
Plugin support not currently being implemented is the second caveat.
qb comes with a host-based adblocker although I cannot offer an intro to it as there is a similar DNS level blocker on my network.
I would love to use it as my main browser, but unfortunately I have a some extensions in Firefox that I can't do without. Really awesome though; would definitely use it otherwise.