MU-INIT(1)

📦
version 1.14.2 · 11 versions
, in ubuntu stonking

💖 MU INIT — the manual page, but make it make sense 💖

okay bestie, gather round, because this is mu-init, aka the first thing you run before anything else in the mu universe even breathes. It's from the General Commands Manual and it's basically the glow-up your message database needs before mu index can do its thing. 🌸

✨ NAME ✨

mu-init — initialize the mu message database. That's it. That's the whole job. Iconic, honestly. 👑

✨ SYNOPSIS ✨

mu [COMMON-OPTIONS] init [OPTIONS]

like yes, mu init is the whole vibe, the [OPTIONS] are just the accessories 💅

✨ DESCRIPTION ✨

So <purple>mu init</purple> is the subcommand that sets up the mu message database from scratch. It's giving "unboxing a brand new notebook, but make it email". 📓✨

Once mu init is done doing its thing? Then you can run mu index. Not before. It's a whole sequence, bestie. Order matters. 🫶

✨ INIT OPTIONS ✨

no fr, here's every single one, do not skip, everything is here for a reason:

  • -m, --maildir maildir — Use maildir as the root-maildir. 🌈

By default, mu goes hunting for the root-maildir through the MAILDIR environment variable. If that's not set, it checks ~/Maildir and uses that only if it's an existing directory. And if neither of those works out? Then the --maildir option is required — and it must be an absolute path (though <lavender>~</lavender> expansion does get performed, so you're not completely stranded 🎀).

  • --personal-address email-address-or-regex — Says "hey, this address is mine, it's personal, it's main character energy". This option can be used multiple times, so you can list every single one of your addresses. 👑

Any message where at least one of the contact fields matches a personal address is considered a personal message — and that's what lets you filter stuff in mu-find(1), mu-cfind(1) and mu4e, like filtering out mailing list messages. So useful, no cap. ✨

email-address-or-regex can be either a plain e-mail address (like foo@example.com) or a basic PCRE regular expression (peep pcre(3) for details) wrapped in / (like /foo-.*@example\.com/). Depending on your shell, the argument may need to be quoted. 🌸

A note of warning for mu4e users: any regular expressions you use with --with-address are also used by mu4e. Unfortunately, PCRE regular expressions are not generally compatible with Emacs regular expressions. For instance, (foo|bar) in PCRE syntax has as its Emacs equivalent. 😭

The good news, bestie: mu4e can automatically translate the regular expressions, if you let it, by installing the pcre2el Elisp package. See the mu4e documentation for further details. 🦋

  • --my-address email-address-or-regex — Obsolete alias for --personal-address. it's giving "we keep it around for the old heads" 💀
  • --ignored-address email-address-or-regex — Says "this e-mail address is ignored from the contacts-cache" (and yeah, you can use this one multiple times too). Such addresses then cannot be found with mu-cfind(1) or in the Mu4e contacts cache. 🚫

my-email-address can be either a plain e-mail address or a regexp, just like for the --personal-address option.

  • --max-message-size size — Specifies the maximum size for an e-mail message. Usually, the default of 100000000 bytes should be fine. 🌈
  • --batch-size size — The number of changes after which they are committed to the database. Decreasing the value reduces the memory requirements, at the cost of making indexing substantially slower. Usually, the default of 250000 should be fine. 🧚

Batch-size 0 is interpreted as use the default. ⭐

  • --support-ngrams — Whether to enable support for using ngrams in indexing and query parsing; this can be useful for languages without explicit word breaks, such as Chinese/Japanese/Korean. See NGRAM SUPPORT below for details. 👀
  • --reinit — Reinitialize the database from an earlier version; that is, create a new empty database with the existing settings. This cannot be combined with the other init options. ⚠️

When you have labels defined for messages in your database, mu automatically exports those to a file for importing later. See RESTORING LABELS below. 🎀

  • --muhome — Use a non-default directory to store and read the database, write the logs, etc. By default, mu uses the XDG Base Directory Specification (e.g. on GNU/Linux this defaults to ~/.cache/mu and ~/.config/mu). Earlier versions of mu defaulted to ~/.mu, which now requires --muhome=~/.mu. 💅

The environment variable MUHOME can be used as an alternative to --muhome. The latter has precedence. 👑

✨ NGRAM SUPPORT ✨

mu's underlying Xapian database supports ngrams, which improve searching for languages/scripts that do not have explicit word breaks, such as Chinese, Japanese and Korean. 📚

It is fairly intrusive, and influences both indexing and query-parsing; it is not enabled by default, and is recommended only if you need to search for messages written in such languages. 🙈

When enabled, mu automatically uses ngrams automatically. Xapian environment variables such as XAPIAN_CJK_NGRAM are ignored. 🚫

✨ EXIT CODE ✨

This command returns 0 upon successful completion, or a non-zero exit code otherwise.

  • 0 — success 🎉
  • 2 — no matches found. Try a different query 🤔
  • 11 — database schema mismatch. You need to re-initialize mu, see mu-init(1) 😭
  • 19 — failed to acquire lock. Some other program has exclusive access to the mu database 🔒
  • 99 — caught an exception 💀

✨ RESTORING LABELS ✨

When you have any labels defined for your database, mu automatically exports those to a file in the mu cache directory; you see this in the --init output. 👀

$ mu init --reinit
exported labels to: /home/user/.cache/mu/mu-export-2025-08-16-13:43:27.txt

You can restore those labels after re-indexing, e.g.,

$ mu label import /home/user/.cache/mu/mu-export-2025-08-16-13:43:27.txt

Please see mu-labels(1) for further details. 🫶

✨ EXAMPLE ✨

here's the whole thing in one line, bestie, look at her go:

$ mu init --maildir=~/Maildir --my-address=alice@example.com --my-address=bob@example.com --ignored-address='/.*reply.*/'

✨ REPORTING BUGS ✨

Please report bugs at <https://github.com/djcb/mu/issues>. They wanna hear from you, fr fr. 🐛

✨ AUTHOR ✨

Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> — the legend himself 👑

This manpage is part of mu 1.14.2. 🌸

Copyright © 2008-2026 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. 💜

✨ SEE ALSO ✨

mu-index(1), mu-find(1), mu-labels(1), mu-cfind(1), pcre(3) — go read those next, the lore is deep 🌈

and that's the whole page, bestie!! 🎀 source is mu 1.14.2, manual-section MU INIT(1), and yeah we're legally required to say the trailing date slot out loud, so: MU INIT(1), mu 1.14.2 — go init your database, you absolute icon 💅✨

📦 where this page comes from