About this Manual

This manual covers only the Emacs interface to Notmuch. For information on the command line interface, see section “Description” in the Notmuch Manual Pages. To save typing, we will sometimes use notmuch in this manual to refer to the Emacs interface to Notmuch. When this distinction is important, we’ll refer to the Emacs interface as notmuch-emacs.

Notmuch-emacs is highly customizable via the the Emacs customization framework (or just by setting the appropriate variables). We try to point out relevant variables in this manual, but in order to avoid duplication of information, you can usually find the most detailed description in the variables’ docstring.


notmuch-hello is the main entry point for Notmuch. You can start it with M-x notmuch or M-x notmuch-hello. The startup screen looks something like the following. There are some hints at the bottom of the screen. There are three main parts to the notmuch-hello screen, discussed below. The bold text indicates buttons you can click with a mouse or by positioning the cursor and pressing <return>

Welcome to notmuch You have 52 messages.

Saved searches: [edit]

52 inbox 52 unread

Search: ____________________________________

All tags: [show]

Type a search query and hit RET to view matching threads.
Edit saved searches with the edit button.
Hit RET or click on a saved search or tag name to view matching threads.
= to refresh this screen. s to search messages. q to quit.
Customize this page.

You can change the overall appearance of the notmuch-hello screen by customizing the variable notmuch-hello-sections.

notmuch-hello key bindings

Move to the next widget (button or text entry field)
Move to the previous widget.
Activate the current widget.
Refresh the buffer; mainly update the counts of messages for various saved searches.
Import mail, See Importing Mail
Compose a message
Search the notmuch database using notmuch-search
Print notmuch version

Saved Searches

Since notmuch is entirely search-based, it’s often useful to organize mail around common searches. To facilitate this, the first section of notmuch-hello presents a customizable set of saved searches. Saved searches can also be accessed from anywhere in notmuch by pressing j to access notmuch-jump.

The saved searches default to various common searches such as tag:inbox to access the inbox and tag:unread to access all unread mail, but there are several options for customization:

The list of saved searches, including names, queries, and additional per-query options.
This variable controls how saved searches should be sorted. A value of nil displays the saved searches in the order they are stored in ‘notmuch-saved-searches’.
Controls the number of columns for displaying saved-searches/tags

Known Tags

One special kind of saved search provided by default is for each individual tag defined in the database. This can be controlled via the following variables.

Control how to construct a search (“virtual folder”) from a given tag.
Which tags not to display at all.
Controls the number of columns for displaying saved-searches/tags



Global key bindings

Several features are accessible from anywhere in notmuch through the following key bindings:

Jump to saved searches using notmuch-jump.


Saved searches configured through notmuch-saved-searches can include a “shortcut key” that’s accessible through notmuch-jump. Pressing j anywhere in notmuch followed by the configured shortcut key of a saved search will immediately jump to that saved search. For example, in the default configuration j i jumps immediately to the inbox search. When you press j, notmuch-jump shows the saved searches and their shortcut keys in the mini-buffer.


Importing Mail



Init File

When Notmuch is loaded, it will read the notmuch-init-file (~/.emacs.d/notmuch-config by default) file. This is normal Emacs Lisp file and can be used to avoid cluttering your ~/.emacs with Notmuch stuff. If the file with .elc, .elc.gz, .el or .el.gz suffix exist it will be read instead (just one of these, chosen in this order). Most often users create ~/.emacs.d/notmuch-config.el and just work with it. If Emacs was invoked with the -q or --no-init-file options, notmuch-init-file is not read.