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]

Hit `?’ for context-sensitive help in any Notmuch screen.
Customize Notmuch or 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.

g =

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


notmuch-show-mode is used to display a single thread of email from your email archives.

By default, various components of email messages, (citations, signatures, already-read messages), are hidden. You can make these parts visible by clicking with the mouse button or by pressing RET after positioning the cursor on a hidden part.


Scroll the current message (if necessary), advance to the next message, or advance to the next thread (if already on the last message of a thread).


Copy to kill-ring


Move to next message


Move to previous message (or start of current message)


Move to next matching message


Move to previous matching message


Add or remove arbitrary tags from the current message.


Display full set of key bindings

Display of messages can be controlled by the following variables


Headers that should be shown in a message, in this order.

For an open message, all of these headers will be made visible according to notmuch-message-headers-visible or can be toggled with notmuch-show-toggle-visibility-headers. For a closed message, only the first header in the list will be visible.


Should the headers be visible by default?

If this value is non-nil, then all of the headers defined in notmuch-message-headers will be visible by default in the display of each message. Otherwise, these headers will be hidden and notmuch-show-toggle-visibility-headers can be used to make them visible for any given message.


Show a header line with the current message’s subject.

Copy to kill-ring

You can use the usually Emacs ways of copying text to the kill-ring, but notmuch also provides some shortcuts. These keys are available in notmuch-show, and notmuch-tree. A subset are available in notmuch-search.

c F notmuch-show-stash-filename

Copy filename of current message to kill-ring.

c G notmuch-show-stash-git-send-email

Copy From/To/Cc/Message-Id of current message to kill-ring. Use a form suitable for pasting to git send-email command line.

If invoked with a prefix argument (or NO-IN-REPLY-TO is non-nil), omit –in-reply-to=<Message-Id>.

c I notmuch-show-stash-message-id-stripped

Copy message ID of current message (sans id: prefix) to kill-ring.

c L notmuch-show-stash-mlarchive-link-and-go

Copy an ML Archive URI for the current message to the kill-ring and visit it.

This presumes that the message is available at the selected Mailing List Archive.

If optional argument MLA is non-nil, use the provided key instead of prompting the user (see notmuch-show-stash-mlarchive-link-alist).

c T notmuch-show-stash-tags

Copy tags of current message to kill-ring as a comma separated list.

c c notmuch-show-stash-cc

Copy CC field of current message to kill-ring.

c d notmuch-show-stash-date

Copy date of current message to kill-ring.

If invoked with a prefix argument, copy timestamp of current message to kill-ring.

c f notmuch-show-stash-from

Copy From address of current message to kill-ring.

c i notmuch-show-stash-message-id

Copy id: query matching the current message to kill-ring.

If invoked with a prefix argument (or STASH-THREAD-ID is non-nil), copy thread: query matching the current thread to kill-ring.

c l notmuch-show-stash-mlarchive-link

Copy an ML Archive URI for the current message to the kill-ring.

This presumes that the message is available at the selected Mailing List Archive.

If optional argument MLA is non-nil, use the provided key instead of prompting the user (see notmuch-show-stash-mlarchive-link-alist).

c s notmuch-show-stash-subject

Copy Subject field of current message to kill-ring.

c t notmuch-show-stash-to

Copy To address of current message to kill-ring.

c ?

Show all available copying commands


notmuch-tree-mode displays the results of a “notmuch tree” of your email archives. Each line in the buffer represents a single message giving the relative date, the author, subject, and any tags.


Copy to kill-ring


Displays that message.


Move to next message


Move to previous message


Move to next matching message


Move to previous matching message

o notmuch-tree-toggle-order

Toggle the current search order.

This command toggles the sort order for the current search. The default sort order is defined by notmuch-search-oldest-first.

l notmuch-tree-filter

Filter or LIMIT the current search results based on an additional query string

t notmuch-tree-filter-by-tag

Filter the current search results based on an additional tag

g =

Refresh the buffer


Display full set of key bindings

As is the case with notmuch-search, the presentation of results can be controlled by the variable notmuch-search-oldest-first.


notmuch-unthreaded-mode is similar to notmuch-tree in that each line corresponds to a single message, but no thread information is presented.

Keybindings are the same as notmuch-tree.

Global key bindings

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


Jump to saved searches using notmuch-jump.


Tagging operations using notmuch-tag-jump

C-_ C-/ C-x u: Undo previous tagging operation using notmuch-tag-undo


Saved searches configured through 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.


Tagging operations configured through notmuch-tagging-keys can be accessed via k in notmuch-show, notmuch-search and notmuch-tree. With a prefix (C-u k), notmuch displays a menu of the reverses of the operations specified in notmuch-tagging-keys; i.e. each +tag is replaced by -tag and vice versa.


A list of keys and corresponding tagging operations.

For each key (or key sequence) you can specify a sequence of tagging operations to apply, or a variable which contains a list of tagging operations such as notmuch-archive-tags. The final element is a name for this tagging operation. If the name is omitted or empty then the list of tag changes, or the variable name is used as the name.

The key notmuch-tag-jump-reverse-key (k by default) should not be used (either as a key, or as the start of a key sequence) as it is already bound: it switches the menu to a menu of the reverse tagging operations. The reverse of a tagging operation is the same list of individual tag-ops but with +tag replaced by -tag and vice versa.

If setting this variable outside of customize then it should be a list of triples (lists of three elements). Each triple should be of the form (key-binding tagging-operations name). KEY-BINDING can be a single character or a key sequence; TAGGING-OPERATIONS should either be a list of individual tag operations each of the form +tag or -tag, or the variable name of a variable that is a list of tagging operations; NAME should be a name for the tagging operation, if omitted or empty than then name is taken from TAGGING-OPERATIONS.


Each notmuch buffer supporting tagging operations (i.e buffers in notmuch-show, notmuch-search, notmuch-tree, and notmuch-unthreaded mode) keeps a local stack of tagging operations. These can be undone via notmuch-tag-undo. By default this is bound to the usual Emacs keys for undo.


Undo the previous tagging operation in the current buffer. Uses buffer local variable notmuch-tag-history to determine what that operation was.

Buffer navigation


Cycle through any existing notmuch buffers (search, show or hello).

If the current buffer is the only notmuch buffer, bury it. If no notmuch buffers exist, run notmuch.


Importing Mail


Run “notmuch new” or an external script to import mail.

Invokes notmuch-poll-script, “notmuch new”, or does nothing depending on the value of notmuch-poll-script.


[Deprecated] Command to run to incorporate new mail into the notmuch database.

This option has been deprecated in favor of “notmuch new” hooks (see man notmuch-hooks). To change the path to the notmuch binary, customize notmuch-command.

This variable controls the action invoked by notmuch-poll-and-refresh-this-buffer (bound by default to ‘G’) to incorporate new mail into the notmuch database.

If set to nil (the default), new mail is processed by invoking “notmuch new”. Otherwise, this should be set to a string that gives the name of an external script that processes new mail. If set to the empty string, no command will be run.

The external script could do any of the following depending on the user’s needs:

1. Invoke a program to transfer mail to the local mail store 2. Invoke “notmuch new” to incorporate the new mail 3. Invoke one or more “notmuch tag” commands to classify the mail

Sending Mail


Emacs consults the variable mail-user-agent to choose a mail sending package for commands like report-emacs-bug and compose-mail. To use notmuch for this, customize this variable to the symbol notmuch-user-agent.

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.