This manual first includes the tutorial, then covers the configuration of Nyxt.
Keybindings and commands
Commands are invoked by pressing specific keys or from the
execute-command menu (
Keybindings are represented like this: 'C-x'. In this example, 'C' is a shortcut for the modifier 'control', and 'x' represents the character 'x'. To input the 'C-x' keybinding you would keep 'control' pressed and then hit 'x'. Multiple key presses can be chained: in 'C-x C-s', you would have to press 'C-x', and then press 'C-s'.
Modifier keys legend:
C): Control key
S): Windows key, Command key
M): Alt key, Option key
s): Shift key
Modifiers can be remapped, see the
modifier-translator slot of
C-l: Load URL
C-r: Reload buffer
M-l: Load URL in new buffer
C-]: Switch buffer
M-[: Backwards history
M-]: Forwards history
C-j: Follow link in current buffer
C-J: Follow link in new buffer
C-space: Run a command by name
f1 b: List all bindings for the current buffer
Nyxt uses the concept of buffers instead of tabs. Unlike tabs, buffers are fully separated, each buffer having its own behavior and settings.
Each buffer has separate instances of modes, which means that altering the settings of a mode in a buffer does not impact other buffers. Mode specific functions/commands are only available when a mode is enabled for the current buffer.
Each mode has an associated mode toggler which is a command of the same name that toggles the mode for the current buffer.
The prompt buffer is a menu that will appear when a command requests user
input. For example, when invoking the
set-url command, you must
supply the URL you would like to navigate to. The prompt buffer can provide
suggestions. The list of suggestions will automatically narrow down to those
matching your input as you type.
return): Validate the selected suggestion(s) or the current input if there is no suggestion.
M-return) : Query the user for an action to run over the selected suggestion(s).
Some commands support multiple selections, for instance
can delete all selected buffers at once. When the input is changed and the
suggestions are re-filtered, the selection is not altered even if the marked
elements don't show.
When at least one suggestion is marked, only the marked suggestions are processed upon return. The suggestion under the cursor is not processed if not marked.
M-space): Select or deselect the current suggestion.
M-a): Select all currently-displayed suggestions.
M-u): Deselect all currently-displayed suggestions.
M-m): Toggle the mark of all currently-displayed suggestions.
C-]): Change which attributes are displayed in the suggestions list.
The message area represents a space (typically at the bottom of a window)
where Nyxt outputs messages back to you. To view the history of all messages,
invoke the command
The status area is where information about the state of that buffer is printed (typically at the bottom of a window). By default, this includes the active modes, the URL, and the title of the current buffer.
Moving within a buffer
To move within a buffer, several commands are provided:
keypaddown): Scroll down the current page.
keypadup): Scroll up the current page.
keypadnext): Scroll down by one page height.
keypadpageup): Scroll up by one page height.
C-down): Scroll to the bottom of the current page.
C-up): Scroll to the top of the current page.
Setting the URL
When ambiguous URLs are inputted, Nyxt will attempt the best guess it can. If you do not supply a protocol in a URL, HTTPS will be assumed. To visit a site supporting only the less secure HTTP, you must explicitly type the full URL including the 'http://' prefix.
C-l): Set the URL for the current buffer, completing with history.
M-l): Prompt for a URL and set it in a new focused buffer.
C-t): Switch to a new buffer.
M-down): Switch buffer using fuzzy completion to quickly find whatever buffer you are looking for.
C-]): Switch to the next buffer in the buffer tree.
C-[): Switch to the previous buffer in the buffer tree.
Copy and paste
Unlike other web browsers, Nyxt provides powerful ways of copying and pasting content via different commands. Starting from:
C-c): Copy selected text to clipboard.
C-v): Paste from clipboard into active element.
Passing through webpage's data:
M-c l): Save current URL to clipboard.
M-c t): Save current page title to clipboard.
UNBOUND): Copy placeholder text to clipboard.
M-c h): Show a set of element hints, and copy the URL of the user inputted one.
Leveraging password managers:
UNBOUND): Query username and copy to clipboard.
UNBOUND): Query password and copy to clipboard.
UNBOUND) : Copy password prompting for all the details without suggestions.
UNBOUND): Show `*browser*' clipboard ring and paste selected entry.
UNBOUND): Show buffer with Lisp version, Lisp features, OS kernel, etc.
Link-hinting allows you to visit URLs on a page without using the mouse. Invoke one of the commands below: several hints will appear on screen and all links on the page will be listed in the prompt buffer. You can select the hints by matching against the hint, the URL or the title.
C-j): Show a set of element hints, and go to the user inputted one in the current buffer.
C-u C-j) : Show a set of element hints, and open the user inputted one in a new visible active buffer.
C-J): Show a set of element hints, and open the user inputted one in a new buffer (not set to visible active buffer).
Using the buffer history
History is represented as a tree that you can traverse: when you go back in history, then follow a new URL, it effectively creates a new branch without deleting the old path. The tree makes sure you never lose track of where you've been.
M-]): Go to forward URL in history.
M-[): Go to parent URL in history.
M-s-right): Query forward-URL to navigate to.
M-s-left): Query parent URL to navigate back to.
C-M-right) : Query URL to forward to, from all child branches.
C-M-left): Query URL to go to, from the whole history.
You can also view a full tree of the history for a given buffer by invoking the command 'buffer-history-tree'.
Nyxt can search a single buffer or multiple buffers at the same time.
You can view suggestions for search results in the prompt buffer in one place rather than having to jump around in a buffer (or multiple buffers).
C-f): Search on the current buffer.
UNBOUND): Search multiple buffers.
M-f): Remove all search hints.
The bookmark file
made to be human readable and editable. Bookmarks can have the following
:url: The URL of the bookmark.
:title: The title of the bookmark.
:tags: A list of strings. Useful to categorize and filter bookmarks.
C-d): Bookmark the URL of BUFFER.
C-m C-s): Bookmark the currently opened page(s) in the active buffer.
C-m u): Allow the user to bookmark a URL via minibuffer input.
C-m g): Show link hints on screen, and allow the user to bookmark one.
C-m o): Set the URL for the current buffer from a bookmark.
C-m k): Delete bookmark(s) matching URLS-OR-BOOKMARK-ENTRIES.
C-b): List all bookmarks in a new buffer.
application-mode forwards all keys to the renderer.
For instance, using the default binding of Nyxt (
web-cua-map ) the
autofill . Suppose a user is
using their email client which also uses
C-i for the italic
command. Thus, after executing
binding is associated with the webpage's italic command instead of
. Finally, the user can return to their configuration just by executing
Enable, disable, and toggle multiple modes
enable-mode allows the user to apply multiple modes
dark-mode ) to multiple
buffers at once. Conversely, it is possible to revert this action by executing
disable-mode while choosing exactly the same buffers and modes
previously selected. Finally,
toggle-mode also allows activation
and deactivation of multiple modes, but only for the current buffer.
Reduce bandwidth usage via:
UNBOUND): Disable images in current buffer.
UNBOUND): Disable WebGL in current buffer.
Select text without a mouse. Nyxt's
visual-mode imitates Vim's
visual mode (and comes with the CUA and Emacs-like keybindings out of the box,
too). Activate it with the
Visual mode provides the following commands:
C-c): Quit visual mode.
UNBOUND): Add hints to text elements on the page and query them.
UNBOUND): Toggle the mark.
right): Move caret forward by a character.
backspace): Move caret backward by a character.
UNBOUND): Move caret forward by a word.
UNBOUND): Move caret backward by a word.
down): Move caret forward by a line.
up): Move caret backward by a line.
keypadhome): Move caret to the beginning of the line.
keypadend): Move caret to the end of the line.
UNBOUND): Move caret forward to next end of sentence.
UNBOUND): Move caret backward to start of sentence.
Commands designed to ease the use for CUA users (but available to all users):
s-right): Set mark and move caret forward by a character.
s-left): Set mark and move caret backward by a character.
s-down): Set mark and move caret forward by a line.
s-up): Set mark and move caret backward by a line.
A note for
emacs-mode users: unlike in Emacs, in Nyxt the command
UNBOUND) is bound to
Shift-space, as C-space is bound to 'execute-command, overriding any mode
keybinding. If you want to toggle mark with C-space, you'll need to set your own
override-map such that C-space is not bound. An example:
(define-configuration buffer ((override-map (let ((map (make-keymap "override-map"))) (define-key map "M-x" 'execute-command)))))
Nyxt has many facilities for automation. For instance, it is possible to automate the reading experience:
UNBOUND): Mode for automatically scrolling up and down the page.
Symmetrically, it is possible to automate the filling of forms:
C-i): Fill in a field with a value from a saved list.
UNBOUND): Toggle all checkboxes.
In addition, it is possible to automate actions over time:
UNBOUND): Reload the current buffer every 5 minutes.
UNBOUND): Repeat a function every seconds prompts if seconds and or function are not provided.
Or even automate actions based on conditions:
UNBOUND): Mode to repeat a simple action/function repetitively until stopped.
UNBOUND): Refreshes the buffer when associated local file is changed.
Nyxt also offers a no-code interface to build automation via Common Lisp macros:
UNBOUND): Edit a macro.
Lastly, the command
PROCESS-MODE must be highlighted:
UNBOUND): Conditional execution a file/directory-related actions in a separate thread.
PROCESS-MODE is actually a building block for other modes
previously mentioned, such as
REPEAT-MODE . The extension
relationship goes further, since
CRUISE-CONTROL-MODE is in its turn
an extension and a composition of
. Further extensions and compositions can be creatively tailor-made by users to
automate their own use of Nyxt.
C-0) : Control the page zoom.
C-i): See the
UNBOUND): Open file in Nyxt or externally. See
C-u C-o): Edit the current input field using `external-editor-program'.
The Nyxt help system
Nyxt provides introspective and help capabilities. All commands, classes, slots, variables, functions and bindings can be inspected for definition and documentation.
f1 f1): Open up a small help buffer.
f1 t): Show the tutorial. This is the tutorial.
f1 k): Display binding of user-inputted keys.
f1 b): Show a buffer with the list of all known bindings for the current buffer.
f1 c): Inspect a command and show it in a help buffer.
f1 f): Inspect a function and show it in a help buffer.
f1 v): Inspect a variable and show it in a help buffer.
f1 C): Inspect a class and show it in a help buffer.
f1 s): Inspect a slot and show it in a help buffer.
UNBOUND): Inspect anything and show it in a help buffer.
A good starting point is to study the documentation of the classes
Nyxt is written in the Common Lisp programming language which offers a great perk: everything in the browser can be customized by the user, even while it's running!
To get started with Common Lisp, we recommend checking out our web page: Learn Lisp . It contains numerous pointers to other resources, including free books both for beginners and seasoned programmers.
Nyxt provides a mechanism for new users unfamiliar with Lisp to customize
Nyxt. Start by invoking the commands
describe-slot . You can press the button marked 'Configure' to change
the value of a setting. The settings will be applied immediately and saved for
future sessions. Please note that these settings will not alter existing object
Settings created by Nyxt are stored in
Any settings can be overridden manually by
The following section assumes knowledge of basic Common Lisp or a similar programming language.
Nyxt configuration can be persisted in the user file
/home/doe/.config/nyxt/init.lisp (create the parent folders if
(define-configuration buffer ((default-modes (append '(noscript-mode) %slot-default%))))
define-configuration macro can be used to customize the slots
of classes like the browser, buffers, windows, etc. Refer to the class and slot
documentation for the individual details.
To find out about all modes known to Nyxt, run
and type 'mode'.
Slots store values that can be either accessed (get) or changed (set). Setting
new values for slots allows many possibilities of customization. For instance,
keyboard layouts vary across the world. The slot
the default value of
ABCDEFGHIJKLMNOPQRSTUVWXYZ . If the user has
an American keyboard, they can do:
- Execute command
f1 s) ;
- Press the button
- Insert the string "asfdghjkl" .
This will make link-hinting more comfortable for this user. In addition, other
similar approaches of customization can be applied to slots such as
spell-check-language , which can be expanded to do the spelling-check of
other languages besides English.
Web buffers and internal buffers
A `internal-buffer' is used for Nyxt-specific, internal pages such as the tutorial and the description pages. A `web-buffer' is used for web pages. Both the `web-buffer' and the `internal-buffer' classes inherit from the `buffer' class.
You can configure a `buffer' slot and it will cascade down as a new default for both the `internal-buffer' and `web-buffer' classes- unless this slot is specialized by these child classes.
Nyxt supports multiple bindings schemes such as CUA (the default),
Emacs or vi. Changing scheme is as simple as running the corresponding mode,
emacs-mode . To make the change persistent across sessions,
add the following to your configuration:
- vi bindings:
(define-configuration buffer ((default-modes (append '(vi-normal-mode) %slot-default%))))
- Emacs bindings:
(define-configuration buffer ((default-modes (append '(emacs-mode) %slot-default%))))
You can create new scheme names with
Also see the
scheme-name class and the
To extend the bindings of a specific mode, you can extend the mode with
define-configuration and extend its binding scheme with
define-scheme . For example:
(define-configuration base-mode ((keymap-scheme (define-scheme (:name-prefix "my-base" :import %slot-default%) scheme:vi-normal (list "g b" (make-command switch-buffer* () (switch-buffer :current-is-last-p t)))))))
override-map is a keymap that has priority over all other
keymaps. By default, it has few bindings like the one for
. You can use it to set keys globally:
(define-configuration buffer ((override-map (let ((map (make-keymap "override-map"))) (define-key map "M-x" 'execute-command "C-space" 'nothing)))))
nothing command is useful to override bindings to do nothing.
Note that it's possible to bind any command, including those of disabled modes
that are not listed in
In addition, a more flexible approach is to create your own mode with your custom keybindings. When this mode is added first to the buffer mode list, its keybindings have priorities over the other modes. Note that this kind of global keymaps also have priority over regular character insertion, so you should probably not bind anything without modifiers in such a keymap.
(defvar *my-keymap* (make-keymap "my-map")) (define-key *my-keymap* "C-f" 'nyxt/web-mode:history-forwards "C-b" 'nyxt/web-mode:history-backwards) (define-mode my-mode () "Dummy mode for the custom key bindings in `*my-keymap*'." ((keymap-scheme (keymap:make-scheme scheme:cua *my-keymap* scheme:emacs *my-keymap* scheme:vi-normal *my-keymap*)))) (define-configuration (buffer web-buffer) ((default-modes (append '(my-mode) %slot-default%))))
Bindings are subject to various translations as per
. By default if it fails to find a binding it tries again with inverted shifts.
For instance if
C-x C-F fails to match anything
is tried. See the default value of
keymap:*translator* to learn how
to custsomize it or set it to
nil to disable all forms of
search-engines buffer slot documentation. Bookmarks can
also be used as search engines, see the corresponding section.
Nyxt comes with some default search engines for
duckduckgo.com . The following example shows one way to add new search
(defvar *my-search-engines* (list '("python3" "https://docs.python.org/3/search.html?q=~a" "https://docs.python.org/3") '("doi" "https://dx.doi.org/~a" "https://dx.doi.org/")) "List of search engines.") (define-configuration buffer ((search-engines (append (mapcar (lambda (engine) (apply 'make-search-engine engine)) *my-search-engines*) %slot-default%))))
Note that the last search engine is the default one. For example, in order to make python3 the default, the above code can be slightly modified as follows.
(defvar *my-search-engines* (list '("doi" "https://dx.doi.org/~a" "https://dx.doi.org/") '("python3" "https://docs.python.org/3/search.html?q=~a" "https://docs.python.org/3"))) (define-configuration buffer ((search-engines (append %slot-default% (mapcar (lambda (engine) (apply 'make-search-engine engine)) *my-search-engines*)))))
You can configure which actions to take depending on the URL to be loaded. For
instance, you can configure which Torrent program to start to load magnet links.
url-dispatching-handler function documentation.
list-downloads command and the
buffer slot documentation.
Proxy and Tor
Creating your own invokable commands is similar to creating a Common Lisp
function, except the form is
define-command instead of
. If you want this command to be invokable outside of the context of a mode, use
(define-command-global bookmark-url () "Query the user which URL to bookmark." (let ((url (prompt :prompt "Bookmark URL" :sources (make-instance 'prompter:raw-source)))) (bookmark-add url)))
prompt-buffer class documentation for how to write write
Hooks provide a powerful mechanism to tweak the behaviour of various events that occur in the context of windows, buffers, modes, etc.
A hook holds a list of handlers . Handlers are named and typed functions. Each hook has a dedicated handler constructor.
Hooks can be 'run', that is, their handlers are run according to the
combination slot of the hook. This combination is a function of the
handlers. Depending on the combination, a hook can run the handlers either in
parallel, or in order until one fails, or even compose them (pass the
result of one as the input of the next). The handler types specify which input
and output values are expected.
Many hooks are executed at different points in Nyxt, among others:
- Global hooks, such as
- Window- or buffer-related hooks.
- Commands 'before' and 'after' hooks.
- Modes 'enable' and 'disable' hooks.
For instance, if you want to force 'old.reddit.com' over 'www.reddit.com', you can set a hook like the following in your configuration file:
(defun old-reddit-handler (request-data) (let ((url (url request-data))) (setf (url request-data) (if (search "reddit.com" (quri:uri-host url)) (progn (setf (quri:uri-host url) "old.reddit.com") (log:info "Switching to old Reddit: ~s" (render-url url)) url) url))) request-data) (define-configuration web-buffer ((request-resource-hook (hooks:add-hook %slot-default% (make-handler-resource #'old-reddit-handler)))))
url-dispatching-handler for a simpler way to achieve the
Or, if you want to set multiple handlers at once,
(define-configuration web-buffer ((request-resource-hook (reduce #'hooks:add-hook (mapcar #'make-handler-resource (list #'old-reddit-handler #'my-other-handler)) :initial-value %slot-default%))))
Some hooks like the above example expect a return value, so it's important to
make sure we return
request-data here. See the documentation of the
respective hooks for more details.
Data paths and data profiles
Nyxt provides a uniform configuration interface for all data files persisted
to disk (bookmarks, cookies, etc.). To each file corresponds a
data-profile is a unique but customizable object that
helps define general rules for data storage. Both data-paths and data-profiles
compose, so it's possible to define general rules for all data-paths (even for
those not known in advance) while it's also possible to specialize some
data-paths given a data-profile.
The data-profile can be set from command line and from the configuration file.
You can list all known data profiles (including the user-defined profiles) with
--list-data-profiles command-line option.
The data-paths can be passed a hint from the
line option, but each data-path and data-profile rules are free to ignore it.
expand-default-path helper function uses the --with-path value
first, then fallback to a default. See its documentation for more details.
When the data path ends with the
.gpg extension, your GnuPG key
is used to decrypt and encrypt the file transparently. Refer to the GnuPG
documentation for how to set it up.
Note that the socket and the initialization data-paths cannot be set in your configuration (the socket is used before the initialization file is loaded). Instead you can specify these paths from their respective command-line option. You can instantiate a unique, separate Nyxt instance when you provide a new socket path. This is particularly useful in combination with data profiles, e.g. to develop Nyxt or extensions.
Example to create a development data-profile that stores all data in
/tmp/nyxt and stores bookmark in an encrypted file:
(define-class dev-data-profile (data-profile) ((name :initform "dev")) (:documentation "Development profile.")) (defmethod nyxt:expand-data-path ((profile dev-data-profile) (path data-path)) "Persist data to /tmp/nyxt/." (expand-default-path (make-instance (class-name (class-of path)) :basename (basename path) :dirname "/tmp/nyxt/"))) (defmethod nyxt:expand-data-path ((profile dev-data-profile) (path history-data-path)) "Persist history to default location." (expand-data-path *global-data-profile* path)) ;; Make new profile the default: (define-configuration buffer ((data-profile (make-instance (or (find-data-profile (getf *options* :data-profile)) 'dev-data-profile))) (bookmarks-path (make-instance 'bookmarks-data-path :basename "~/personal/bookmarks/bookmarks.lisp.gpg"))))
Then you can start a separate instance of Nyxt using this profile with
nyxt --data-profile dev --socket /tmp/nyxt.socket .
Nyxt provides a uniform interface to some password managers including KeepassXC and Password Store . The supported
installed password manager is automatically detected. See the
password-interface buffer slot for customization.
You may use the
define-configuration macro with any of the
password interfaces to configure them. Please make sure to use the package
prefixed class name/slot designators within the
UNBOUND): Query for name and new password to persist in the database.
UNBOUND): Query password and copy to clipboard.
Much of the visual style can be configured by the user. Search the class slots
for 'style'. To customize the status area, see the
You can evaluate code from the command line with
--load . From a shell:
$ nyxt --no-init --eval '+version+' --load my-lib.lisp --eval '(format t "Hello ~a!~&" (my-lib:my-world))'
You can evaluate multiple --eval and --load in a row, they are executed in the order they appear.
You can also evaluate a Lisp file from the Nyxt interface with the
load-file command. For convenience,
(re)loads your initialization file.
You can even make scripts. Here is an example foo.lisp:
#!nyxt --script (format t "~a~&" +version+)
--eval and --load can be commanded to operate over an existing instance instead of a separate instance that exits immediately.
The `remote-execution-p' slot of the `browser' class of the remote instance must be non-nil.
To let know a private instance of Nyxt to load a foo.lisp script and run its `foo' function:
nyxt --data-profile nosave --remote --load foo.lisp --eval '(foo)'
To install an extension, copy inside the
Extensions are regular Common Lisp systems.
A catalogue of extensions is available in the
file in the source repository.
Nyxt delegates video support to third-party plugins.
When using the WebKitGTK backends, GStreamer and its plugins are leveraged. Depending on the video, you will need to install some of the following packages:
On Debian-based systems, you might be looking for (adapt the version numbers):
For systems from the Fedora family:
After the desired plugins have been installed, clear the GStreamer cache at
~/.cache/gstreamer-1.0 and restart Nyxt.
If some websites systematically crash, try to install all the required Gstreamer plugins as mentioned in the 'Playing videos' section.
Input method support (CJK, etc.)
Depending on your setup, you might have to set some environment variables or run some commands before starting Nyxt, for instance
GTK_IM_MODULE=xim XMODIFIERS=@im=ibus ibus --daemonize --replace --xim
You can persist this change by saving the commands in your
Font size on HiDPI displays
On HiDPI displays, the font size used for displaying web and Nyxt's prompt-buffer content might be too tiny.
To fix this issue when using the WebKitGTK render, export the following environment variable before starting Nyxt:
export GDK_SCALE=2 export GDK_DPI_SCALE=0.5 nyxt
StumpWM mouse scroll
If the mouse scroll does not work for you, see the StumpWM FAQ for a fix.
Blank WebKit web-views
If you are experiencing problems with blank web-views on some sites you can
try to disable compositing. To disable compositing from your initialization
file, you can do the following:
(setf (uiop:getenv "WEBKIT_DISABLE_COMPOSITING_MODE") "1")