1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
2 # Getting Started with Notmuch
4 *This is a work in progress.*
8 This is your friendly guide and tutorial to getting started with Notmuch. It
9 will help you through the first steps of setting up Notmuch.
11 All Notmuch commands have [[manual pages|manpages]]. Please refer to them for
16 In order to use Notmuch, you will need to have your email messages stored in
17 your local filesystem, one message per file. For example,
18 [Maildir](http://cr.yp.to/proto/maildir.html), Maildir++, and MH formats work
19 like this, while [mbox](https://en.wikipedia.org/wiki/Mbox) does not. Storing
20 the messages one message per file is the only hard dependency for trying out
23 We will get back to delivering messages later, for now we'll just assume you
24 already have messages in this format.
28 On Linux, the easiest way to install Notmuch is through your distribution's
29 package repository. If you're installing Notmuch from a [git
30 checkout](https://git.notmuchmail.org/git/notmuch) or a [source
31 release](https://notmuchmail.org/releases/), please refer to the
32 [INSTALL](https://git.notmuchmail.org/git/notmuch/blob/HEAD:/INSTALL) document.
36 To configure Notmuch, just run
40 This will interactively guide you through the setup process, and save the
41 configuration to `$HOME/.notmuch-config`. If you'd like to change the
42 configuration in the future, you can either edit that file directly, or run
45 This step only modifies the configuration file.
49 Notmuch needs a search database to operate. The next step is to run
53 to index all your messages in the search database. The database will be stored
54 in `.notmuch` directory under your mail store. The database is not a replacement
55 or storage for your messages; it's just an index to find the right message
58 Notmuch does not modify or delete your mails. This is one of the main design
59 principles of Notmuch. (The only exception is renaming files upon tagging
60 according to the Maildir specification if the `maildir.synchronize_flags`
61 configuration option is set.) It should be safe to try Notmuch.
63 Depending on the amount of mail you have the initial indexing process can take a
64 long time, so expect that. Also, the resulting database will require roughly the
65 same amount of storage space as your current collection of email.
67 After this step, you can try out the [[Notmuch command-line
68 interface|manpages]], or [[Notmuch Emacs interface|notmuch-emacs]].
70 ## Converting Existing mbox to Maildir
72 The [`mb2md`](http://batleth.sapienti-sat.org/projects/mb2md/) tool can be used
73 to convert existing mbox files to Maildir.
75 Beware that the source and destination directory options to `mb2md` are relative
76 to the user's home directory, not relative to the current working directory.
78 ## Delivering New Messages
80 Notmuch itself does not receive messages. There is no IMAP or POP support. You
81 will need to set up other tools, such as fetchmail, offlineimap, or mbsync, to
84 There are two ways to deliver and index messages:
86 * Use an external tool (such as offlineimap or mbsync) to deliver the messages
87 to your mail store, and run `notmuch new` to discover and index the newly
88 delivered messages (and any other changes in the mail store).
90 * Use an external tool (such as fetchmail) receive the messages, and configure
91 the tool to use `notmuch insert` as a Mail Delivery Agent to deliver the
92 messages to your mail store and index them.
94 ## Automation Via Hooks
96 Notmuch supports running [[user defined hooks|manpages/notmuch-hooks-5]] before
97 or after certain commands. Hooks can be arbitrary executable programs or
98 scripts. For example, if you always run your mail delivery tool first and
99 `notmuch new` after that, you can run the tool from Notmuch `pre-new` hook, and
100 simply run `notmuch new` to do both. If you always do some tagging after
101 indexing of new messages, you may want to set up a `post-new` or `post-insert`
102 hook to do that automatically.
104 ## Backing Up and Restoring the Database
106 The Notmuch database contains a search index of your messages, along with all
107 the tags you've added to your messages. The search index can be regenerated by
108 indexing the messages again, but the tags will be lost if the database is
109 lost. (If you have `maildir.synchronize_flags` configuration option enabled,
110 also some of the tags can be regenerated from maildir flags.)
112 To create a plain-text dump of the tags, run
114 notmuch dump --output=dump.txt
116 To restore the tags from the dump, run
118 notmuch restore --input=dump.txt
122 Did not like it after all? All you need to do is remove the database and the
123 configuration file. The database is stored in the `.notmuch` directory under
124 your mail store. And your mail store is at `notmuch config get database.path`.
126 You may want to use the `notmuch dump` command to create a backup of any tags
127 you've added before removing the database.