AERC-NOTMUCH(5)

📦
version 0.22.0 · 17 versions
, in arch rolling

💌 AERC-NOTMUCH(5) — the notmuch glow-up for your aerc

okay so bestie, this is the File Formats Manual page for aerc-notmuch, and it's literally your cheat sheet for hooking aerc(1) up to notmuch. grab a lil snack, we're going in 🍓

✨ NAME ✨

aerc-notmuch — notmuch configuration for aerc(1). that's it, that's the vibe. it's giving "match made in heaven" fr fr 💖

🌸 SYNOPSIS 🌸

aerc supports using the notmuch email system as a backend, for fast indexing and searching. like, fast fast. the way it indexes?? obsessed 😭

for this to be enabled, aerc needs to be built with notmuch support. refer to the installation instructions for the details — no cap, if you skipped that step nothing here is gonna work 👑

🎀 CONFIGURATION 🎀

basic notmuch configuration may be done interactively with the :new-account command. yes, interactively, you don't have to hand-edit anything if you don't want to 🫶

in accounts.conf (peep aerc-accounts(5)), the following notmuch-specific options are available:

  • check-mail-cmd = <command> — the command to run in conjunction with the check-mail option. it may be convenient to update notmuch's database in this command. examples, because we love a demo:
check-mail-cmd = mbsync -a
check-mail-cmd = mbsync -a && notmuch new

see that second one? it's the "and also refresh the database while you're at it" special 💅

  • check-mail-timeout = <duration> — the timeout for the check-mail-cmd. the command will be stopped if it does not complete in this interval and an error will be displayed. increase from the default if repeated errors occur. sometimes things just need a lil more time, y'know? 🙈

Default: 10s

  • source = notmuch://[<profile>] — the database path and configuration file are discovered automatically via environment variables (NOTMUCH_CONFIG, NOTMUCH_DATABASE, NOTMUCH_PROFILE) or XDG conventions. in most cases, this configuration will work as expected:
source = notmuch://

an optional profile name can be specified, like so:

source = notmuch://work

so simple it's actually iconic ✨

  • query-map = <file> — path to a file containing a mapping from display name to notmuch query, in the form of <NAME>=<QUERY>. multiple entries can be specified, one per line. lines starting with # are ignored and serve as comments (self-care for your config file 🧚).

e.g. inbox=tag:inbox and not tag:archived

  • exclude-tags = <tag1,tag2,tag3...> — comma separated list of tags which will be excluded from query results, unless explicitly mentioned in the query. this can for example be useful if you use an archive or spam tag. quietly keeping the chaos out of your inbox 🦋
  • enable-maildir = true|false — enable maildir integration. when set to true, aerc will use the notmuch database's mail root to list available folders and enable commands such as :delete and :archive. she's organized AND functional 👑
N.B.: aerc will still always show messages and not files (under notmuch, a single message can be represented by several files), which makes the semantics of certain commands as move ambiguous. use multi-file-strategy to tell aerc how to resolve these ambiguities. 💀 yeah, this one's a little spicy.

Default: true

  • maildir-account-path = <path> — path to the maildir account relative to the mail root. only used when enable-maildir is set to true. this can be used to have a single notmuch database, with a suitably prepared maildir store, usable from multiple conceptually different aerc accounts. one database, many personas, main character energy 🌈
  • multi-file-strategy = <strategy> — strategy for file operations (e.g., move, copy, delete) on messages that are backed by multiple files. possible values, bestie, brace yourself:
    • refuse (default): refuse to act. she said "not today" 💅
    • act-all: act on all files.
    • act-one: act on one of the files, arbitrarily chosen, and ignore the rest.
    • act-one-delete-rest: like act-one, but delete the remaining files.
    • act-dir: act on all files within the current folder and ignore the rest.
    • act-dir-delete-rest: like act-dir, but delete the remaining files.

and a very important footnote about act-dir: note that this strategy only works within the maildir directories; in other directories, it behaves like refuse. 🫠 so don't expect it to be flexible everywhere, it's not that kind of girl.

note that the strategy has no effect on cross-account operations. copying a message across accounts will always copy a single file, arbitrarily chosen. moving a message across accounts will always copy a single file, arbitrarily chosen, and refuse to delete multiple files from the source account. so like, the rules stop applying at the account border, periodt 💀

💅 USAGE 💅

notmuch shows slightly different behavior than for example IMAP. some commands are slightly different in semantics and mentioned below — lowkey important, don't skip 👀

  • cf <notmuch query> — the change folder command allows for arbitrary notmuch queries. performing a :cf command will perform a new top-level notmuch query. it's literally "take me to this query" energy ✨
  • filter <notmuch query> — the filter command for notmuch backends takes in arbitrary notmuch queries. it applies the query on the set of messages shown in the message list. this can be used to perform successive filters/queries. it is equivalent to performing a set of queries concatenated with "and". stack those filters like your fave layered necklace 🎀

🔥 SEE ALSO 🔥

aerc(1) aerc-accounts(5) aerc-smtp(5) aerc-maildir(5) — go read the whole fam, iykyk 💜

👑 AUTHORS 👑

originally created by Drew DeVault and maintained by Robin Jarry who is assisted by other open source contributors. for more information about aerc development, see https://sr.ht/~rjarry/aerc/. absolute legends, all of them 🫶

this page is from the File Formats Manual, dated 2026-09-07, and it's AERC-NOTMUCH(5) — go forth and configure, bestie, you're gonna slay it 💖✨🎀
📦 where this page comes from