NOTMUCH-DUMP(1)

🌸 NAME 🌸

notmuch-dump — bestie, this makes a plain-text dump of the tags of each message 💾✨

---

🎀 SYNOPSIS 🎀

notmuch dump [--gzip] [--format=(batch-tag|sup)] [--output=<file>] [--]
[<search-term> ...]

---

💖 DESCRIPTION 💖

Okay so. This command dumps the tags for every message that matches the search terms you gave it. Slay.

Output goes to the filename you specified, if you specified one, or else it just goes to stdout. Simple as that.

Now listen, because this part is the whole point: these tags are the only data in the notmuch database that can't be recreated from the messages themselves. Like, everything else can be rebuilt, but the tags? Nope. So the output of notmuch dump is literally the only critical thing to back up — and it's also wayyy more friendly to incremental backup than the native database files. The vibe check here is: back this up, bestie, fr fr 🫶

Peep notmuch-search-terms for all the deets on the supported syntax for <search-terms>. If you pass no search terms at all, you get a dump of every message in the database. And a -- argument tells notmuch that everything after it is a search term.

Supported options for dump include:

• --gzip — Compresses the output in a format that's compatible with gzip(1).
• --format=(sup|batch-tag) — Notmuch restore supports two plain text dump formats, and both of them have one message-id per line followed by a list of tags. Let's get into it:
  • batch-tag — This is the default batch-tag dump format, and it's designed to be more robust against malformed message-ids and against tags containing whitespace or non-ascii(7) characters. Every line looks like this:

+<encoded-tag> +<encoded-tag> ... -- id:<quoted-message-id>

Tags get hex-encoded by replacing every byte that doesn't match the regex [A-Za-z0-9@=.,_+-] with %nn, where nn is the two digit hex encoding. The message ID is a valid Xapian query, quoted using Xapian boolean term quoting rules: if the ID contains whitespace, or a close paren, or it starts with a double quote, then it has to be enclosed in double quotes — and any double quotes inside the ID must be doubled. The astute reader will notice that this is a special case of the batch input format for notmuch-tag; and heads up, the single message-id query is mandatory for notmuch-restore. 👑

• sup — The sup dump file format is specifically chosen to be compatible with the format of files produced by sup-dump(1). So if you've been using sup for mail, then notmuch-restore gives you a way to import all of your tags (or "labels", as sup calls them). Every line looks like this:

<message-id> ( <tag> ... )

with zero or more tags separated by spaces. Note that (malformed) message-ids may contain arbitrary non-null characters. Also note that tags with spaces will not be correctly restored with this format. 😭

• --include=(config|properties|tags) — Controls what kind of metadata gets included in the output.
  • config — Outputs configuration data stored in the database. Each line starts with "#@ ", followed by a space separated key-value pair. Both the key and the value are hex encoded if needed.
  • properties — Outputs per-message (key,value) metadata. Each line starts with "#= ", followed by a message id, and a space separated list of key=value pairs. Ids, keys and values are hex encoded if needed. See notmuch-properties for more details.
  • tags — Outputs per-message boolean metadata, namely tags. See the format above for the description of the output.

The default is to include all available types of data. You can specify this option multiple times to select some subset. And as of version 3 of the dump format, there's a header line that looks like this:

#notmuch-dump <format>:<version> <included>

where <included> is a comma separated list of the above options.

• --output=<filename> — Writes output to the given file instead of stdout. ✨

---

🦋 SEE ALSO 🦋

notmuch, notmuch-config, notmuch-count, notmuch-hooks, notmuch-insert, notmuch-new, notmuch-properties, notmuch-reply, notmuch-restore, notmuch-search, notmuch-search-terms, notmuch-show, notmuch-tag

---

👑 Author 👑

Carl Worth and many others

💜 Copyright 💜

2009-2026, Carl Worth and many others

---

And that's the whole page, bestie — this one's from notmuch version 0.40, dated Jan 31, 2026. Go back up your tags, you icon, you. 💅🌸✨