notmuch

Configure for first use

$ notmuch setup

$ notmuch tag +[custom_tag] "[search_term]"

$ notmuch tag -[custom_tag] "[search_term]"

$ notmuch count --output=[messages|threads] "[search_term]"

$ notmuch search --format=[json|text] --output=[summary|threads|messages|files|tags] "[search_term]"

$ notmuch search --format=[json|text] --output=[summary|threads|messages|files|tags] --limit=[X] "[search_term]"

$ notmuch reply --format=[default|headers-only] --reply-to=[sender|all] "[search_term]"

notmuch [global-options] <command> [command-options] [arguments]

Common Commands:
    notmuch new
    notmuch search [options] <query>
    notmuch show [options] <query>
    notmuch tag [options] (+tag|-tag ...) <query>
    notmuch count [options] <query>
    notmuch config
    notmuch dump
    notmuch restore
    notmuch compact
    notmuch reindex
    notmuch help [command]

--config=<file>
    Specifies an alternative configuration file path instead of the default.

--profile=<name>
    Uses a specific named profile from the configuration file, allowing for multiple notmuch configurations.

--database=<directory>
    Specifies the location of the notmuch database directory, overriding the configured path.

--batch
    Enables batch mode, preventing interactive prompts and useful for scripting.

--color[=always|never|auto]
    Controls color output. 'auto' (default) enables color when output is to a TTY, 'always' forces it, 'never' disables it.

--debug
    Enables debug logging to standard error for diagnostic purposes.

--format=<format>
    Sets the general output format for commands like 'search' or 'show' (e.g., 'json', 'sexp', 'text').

--output=<type>
    Specifically requests JSON or S-expression output for applicable commands (e.g., 'json', 'sexp', 'json-0', 'sexp-0').

--sort=newest-first|oldest-first
    Sorts search results by date, either newest (default) or oldest first.

--reverse
    Reverses the default or specified sort order for results.

--limit=<N>
    Limits the number of results returned by a search query to N.

--offset=<N>
    Skips the first N results, useful for pagination of search results.

--format-string=<string>
    Provides a custom format string for detailed control over output presentation for specific commands.

notmuch is a powerful and fast command-line interface (CLI) tool designed for indexing, searching, and managing large collections of email messages. It operates on email stored in the Maildir format, treating each email as a file in the filesystem. Unlike traditional email clients that rely on hierarchical folders, notmuch uses a flexible tagging system, allowing a single email to be associated with multiple categories simultaneously.

At its core, notmuch leverages the Xapian search engine to provide lightning-fast full-text searches across millions of messages. It does not handle sending or receiving email itself, but rather acts as a robust backend for indexing and searching. This makes it an ideal companion for CLI mail clients like Mutt or powerful text editors like Emacs (via notmuch.el). Its strength lies in its speed, flexible tagging, and powerful search query syntax, making email management efficient and intuitive for technical users.

notmuch is solely an email indexer and search tool; it does not handle sending or receiving email itself. It fundamentally requires emails to be stored in the Maildir format. While highly optimized for speed, performance on extremely large databases (millions of emails) can still be influenced by underlying filesystem and disk I/O characteristics. Its primary interface is the command line, meaning a full email management experience usually requires integration with other tools or email clients.

A core concept of notmuch is its reliance on a tagging system rather than traditional hierarchical folders. Emails are indexed from their filesystem location, and arbitrary tags are then applied to them. An email can have multiple tags (e.g., 'inbox', 'work', 'project-x', 'important'), allowing for far more flexible organization and retrieval than being confined to a single folder.

notmuch utilizes the powerful Xapian query language, enabling sophisticated searches. Users can combine terms with boolean operators (AND, OR, NOT), use wildcards (*), search within specific fields (e.g., from:david, subject:report), and filter by dates (e.g., date:yesterday..today, date:3weeks..ago). This allows for highly precise and rapid retrieval of messages across massive archives.

While notmuch provides a robust command-line interface, it is primarily designed to be a backend tool. It integrates seamlessly with various frontends and other email-related tools. Prominent integrations include notmuch.el for Emacs, various scripts for Mutt, and other community-developed applications like nmapp or alot. These frontends provide a user-friendly interface for interacting with the notmuch database and managing email.

notmuch was created by David Bremner, with its first public announcement and release dating back to 2010. Its development was driven by the growing need for a fast, efficient, and flexible way to search and manage large email archives, particularly those stored in the Maildir format. Traditional folder-based email organization often became cumbersome with large volumes, leading to the adoption of a tagging system. Written primarily in C and leveraging the Xapian search library for indexing, notmuch quickly gained popularity in the open-source community for its robust performance and extensibility.

mutt(1), emacs(1), find(1), grep(1), procmail(1), dovecot(1)