MU-QUERY(7)

📦
version 1.14.2 · 11 versions
, in ubuntu stonking

🌸 NAME 🌸

okay so this is mu-query from the Miscellaneous Information Manual (section 7) — it's the language for finding messages in mu databases. that's it, that's the whole job. 💖

✨ DESCRIPTION ✨

so the mu query language is, like, the language that mu find and mu4e speak when they go looking for messages in mu's Xapian database. it's quite similar to Xapian's default query-parser, but plot twist: it's an independent implementation that's been customized for the mu/mu4e use-case. so yeah, cousin energy, not the same person. 🦋

down here we're gonna give you a structured but informal overview of the query language plus examples. and as a little companion to this, we highly recommend running the mu info fields command to get an up-to-date list of the available fields and flags. it's giving "always current", and we love that. ✨

also!! mu find has the --analyze option, which shows how mu interprets your query — and mu4e has a matching command, mu4e-analyze-last-query. head to the ANALYZING QUERIES section down below for the deets. 💅

NOTE: if you're using queries on the command-line (say, for mu find), you need to quote any characters that would otherwise get interpreted by the shell, like ", *, (, and ). the details are shell-specific bestie, so it depends. and if you're in doubt? the --analyze option is right there for you. 🫶

🎀 TERMS 🎀

the basic building blocks of a query are terms. terms are just normal words like "banana" or "hello"… or words with a field-name prefixed onto them, which makes them apply to just that one field. run mu info fields to see all the available fields, no cap. 🌈

some example queries:

vacation
subject:capybara
maildir:/inbox

terms without an explicit field-prefix (like vacation up there) get interpreted as:

to:vacation or subject:vacation or body:vacation or ...

the language is case-insensitive for terms, and it also tries to "flatten" diacritics — so angtrom matches Ångström. iconic behavior honestly. ✨

if a term has whitespace in it, it needs to be quoted:

subject:"hi there"

that's a so-called phrase query, which means we match against subjects that contain the literal phrase "hi there". phrase queries only work for certain fields — you can spot them because they have the word phrase in their mu info fields search column. 💅

💜 Quoting queries for the shell 💜

remember: you need to escape the quotes on a search query when you're using this from the command-line, or else the shell (or most shells) will process the queries first and mu will never even see them. 😭

in this case, that means the difference between searching for a subject "hi there" versus a subject "hi" plus some word "there" that can show up in any of the combination fields for <empty> — and yes, combination fields get discussed further down, hang tight. 🦋

we can use the --analyze option we mentioned to show the difference:

mu find subject:"hi there" --analyze

query:
       subject:hi there

parsed query:
       (and (subject "hi") (_ "there"))

parsed query (expanded):
       (and (subject "hi") (or (to "there") (cc "there") (bcc "there") (from "there") (subject "there") (body "there") (embed "there")))

Xapian query:
         Query((Shi AND (Tthere OR Cthere OR Hthere OR Fthere OR Sthere OR Bthere OR Ethere)))

and with the quotes escaped:

mu find subject:$

query:
       subject:"hi there"

parsed query:
       (or (subject "hi there") (subject (phrase "hi there")))

Xapian query:
         Query((Shi there OR (Shi PHRASE 2 Sthere)))

we won't dwell on the details of the --analyze output here, but hopefully this shows off the difference between quoted and unquoted queries. 🫶

🔥 LOGICAL OPERATORS 🔥

we can combine terms with logical operators — the binary ones: and, or, xor, plus the unary not, all following the conventional rules for precedence and association. and yes, the operators are case-insensitive. ⭐

you can also group things with ( and ) so you can write:

(subject:beethoven or subject:bach) and not body:elvis

and if you don't explicitly put an operator between terms, and is implied — so these two queries are literally equivalent:

subject:chip subject:dale

subject:chip AND subject:dale

for readability, we recommend the second version. bestie, please, your future self will thank you. 🙈

note that a pure not — like searching for not apples — is quite a "heavy" query. 💀

🦋 WILDCARDS 🦋

wildcards are a Xapian built-in mechanism for matching. love that for them. ✨

a search term with a rightmost * (and only in that position) matches any term that starts with the part before the *. they're less powerful than regular expressions, but also much faster:

an example:

$ mu find "hello*"
quoting the "hello*" is recommended — some shells (but not all) would otherwise expand the * to all the files in the current directory. 🙈

👑 REGULAR EXPRESSIONS 👑

the query language supports matching basic PCRE regular expressions, as per pcre(3), with some limitations. we're fancy like that. 💅

regular expressions are enclosed in //. for example:

subject:/h.llo/          # matches hallo, hello, ...

now, notice the difference between "maildir:/foo" and "maildir:/foo/" — the former matches messages in the "/foo" maildir, while the latter matches all messages in all maildirs that match "foo", such as "/foo", "/bar/cuux/foo", "/fooishbar", and so on. tiny slash, big difference. 😭

regular expressions are more powerful than wildcards, but they're also much slower. and moreover, their behavior in mu can be a bit confusing, thanks to some implementation details. see below for some of the caveats. 💀

🌸 Whitespace in regular expression literals 🌸

to avoid ambiguities in the query parsing, regular expressions must not contain whitespace. so to search for a message with subject "hello world", you can write:

mu find 'subject:/hello\\040world/'

(with the \040 specifying a space in the regular expression, and an extra \ to escape it). in many cases though:

mu find 'subject:/hello.world/'

may be good enough, and easier to type. we love a low-effort slay. 🫶

⭐ Anchors in regular expressions ⭐

since the underlying Xapian database doesn't support regular expressions (it does support wildcards), mu implements regular expression search by matching your regular expression against all the "terms" (words or phrases) that exist in the database for a given field. that's the whole trick. 🎀

and that implementation detail is exactly why "anchored" regular expressions — the ones with ^ and $ marking begin/end, respectively — can get unexpected results. 😭

suppose you want to match all messages that start with "pie", and you search with subject:/^pie/. this also matches messages with subject "apple pie" — since both of those words are indexed as terms separately (as well as phrases), and thus "^pie" matches as well for a message with subject "apple pie". not the vibe you asked for, but it's the vibe you got. 💀

🎀 FIELDS 🎀

okay bestie so we already bumped into a bunch of search fields earlier — subject: and body: said hi 💖 — but this is the FULL roster. every single one. and if you want the whole table with every detail, including the single-char shortcuts, just run:

mu info fields

Here's every field, with its alias, its short form, what flavour of search it does, whether it carries a value, whether it plays nice with sexps, a lil example query, and what it actually means:

  • bcc — alias: none · short: h · search: phrase · value: yes · sexp: yes — e.g. bcc:foo@example.com — Blind carbon-copy recipient 💌
  • body — alias: none · short: b · search: phrase · value: no · sexp: no — e.g. body:capybara — Message plain-text body
  • cc — alias: none · short: c · search: phrase · value: yes · sexp: yes — e.g. cc:quinn@example.com — Carbon-copy recipient
  • changed — alias: none · short: k · search: range · value: yes · sexp: yes — e.g. changed:30M.. — Last change time ⏰
  • date — alias: none · short: d · search: range · value: yes · sexp: yes — e.g. date:20220101..20220505 — Message date
  • embed — alias: none · short: e · search: phrase · value: no · sexp: no — e.g. embed:war OR embed:peace — Embedded text
  • file — alias: none · short: j · search: boolean · value: no · sexp: no — e.g. file:/image\.*.jpg/ — Attachment file name
  • flags — alias: flag · short: g · search: boolean · value: yes · sexp: yes — e.g. flag:unread AND flag:personal — Message properties
  • from — alias: none · short: f · search: phrase · value: yes · sexp: yes — e.g. from:jimbo — Message sender
  • language — alias: lang · short: a · search: boolean · value: yes · sexp: yes — e.g. lang:nl — ISO 639-1 language code for body
  • maildir — alias: none · short: m · search: boolean · value: yes · sexp: yes — e.g. maildir:/private/archive — Maildir path for message
  • list — alias: none · short: v · search: boolean · value: yes · sexp: yes — e.g. list:mu-discuss.example.com — Mailing list (List-Id:)
  • message-id — alias: msgid · short: i · search: boolean · value: yes · sexp: yes — e.g. msgid:abc@123 — Message-Id
  • mime — alias: mime-type · short: y · search: boolean · value: no · sexp: no — e.g. mime:image/jpeg — Attachment MIME-type
  • path — alias: none · short: l · search: boolean · value: yes · sexp: yes — e.g. path:/a/b/Maildir/cur/msg:2,S — File system path to message
  • priority — alias: prio · short: p · search: boolean · value: yes · sexp: yes — e.g. prio:high — Priority
  • references — alias: ref · short: r · search: boolean · value: yes · sexp: yes — e.g. ref:E1rQJDx123@example.com — References to related messages
  • size — alias: none · short: z · search: range · value: yes · sexp: yes — e.g. size:1M..5M — Message size in bytes
  • subject — alias: none · short: s · search: phrase · value: yes · sexp: yes — e.g. subject:wombat — Message subject
  • tags — alias: tag · short: x · search: boolean · value: yes · sexp: yes — e.g. tag:projectx — Message tags
  • thread — alias: none · short: w · search: boolean · value: yes · sexp: no — e.g. thread:abcde789@example.com — Thread a message belongs to
  • to — alias: none · short: t · search: phrase · value: yes · sexp: yes — e.g. to:flimflam@example.com — Message recipient
  • labels — alias: label · short: q · search: boolean · value: yes · sexp: yes — e.g. label:projectx — Message label(s)

🦋 combination fields 🦋

There are also combi-fields — little squad leaders that let you search a bunch of related fields all at once, no cap:

  • recip — covers to, cc, bcc
  • contact — covers to, cc, bcc, from
  • related — covers message-id, references
  • <empty> (the bare, no-field-name vibe) — covers to, cc, bcc, from, subject, body, embed

So like, for instance:

contact:fnorb@example.com

is literally equivalent to:

(from:fnorb@example.com or to:fnorb@example.com or
      cc:from:fnorb@example.com or bcc:fnorb@example.com)

(paste it exactly like that, bestie, yes even the cc:from: bit — it's giving quirky but it's what it is 💅)

📅 DATE RANGES 📅

The date: field takes a date-range, written as the lower bound and the upper bound with .. in between, like a lil sandwich 🥪. You can leave out either the lower or the upper (but not both) and boom — open range.

Dates are in local time and use ISO-8601 format (YYYY-MM-DD HH:MM:SS). You're allowed to drop the right-hand part and mu fills in the rest for you, depending on whether it's the beginning or the end of the range — for example, as a lower bound "2015" gets read as the start of that year, and as an upper bound as the end of the year. bestie it knows what you meant ✨

You can also use /, ., -, : and "T" to make dates more human-readable.

Some examples:

date:20170505..20170602
date:2017-05-05..2017-06-02
date:..2017-10-01T12:00
date:2015-06-01..
date:2016..2016

You can also use the special "dates" now and today:

date:20170505..now
date:today..

Finally, there are relative "ago" times — these express some time before now, and they're a number followed by a unit. The units are s for seconds, M for minutes, h for hours, d for days, w for week, m for months and y for years. Some examples:

date:3m..
date:2017.01.01..5w

📏 SIZE RANGES 📏

The size or z field lets you match size ranges — that is, match messages that have a byte-size within a certain range. The units are b (for bytes), K (for 1000 bytes) and M (for 1000 * 1000 bytes). Some examples:

size:10k..2m
size:10m..

tiny messages, huge messages, all of them get their moment 🌈

🌸 FLAG FIELD 🌸

okay bestie, the flag/g field is how you match message flags. here's the whole menu:

  • draft — shortcut D — category file — Draft (in progress) 🎀
  • flagged — shortcut F — category file — User-flagged ⭐
  • passed — shortcut P — category file — Forwarded message 🦋
  • replied — shortcut R — category file — Replied-to 💬
  • seen — shortcut S — category file — Viewed at least once 👀
  • trashed — shortcut T — category file — Marked for deletion 🗑️
  • new — shortcut N — category maildir — New message ✨
  • signed — shortcut z — category content — Cryptographically signed 🔏
  • encrypted — shortcut x — category content — Encrypted 🔒
  • attach — shortcut a — category content — Has at least one attachment 📎
  • unread — shortcut u — category pseudo — New or not seen message 📬
  • list — shortcut l — category content — Mailing list message 📧
  • personal — shortcut q — category content — Personal message 💌
  • calendar — shortcut c — category content — Calendar invitation 📅

some examples:

flag:attach
flag:replied
g:x

encrypted messages may be signed as well, but this is only visible after decrypting and thus invisible to mu. periodt. 💅

💖 PRIORITY FIELD 💖

the message priority field (prio:) has three possible values: low, normal or high. for instance, to match high-priority messages:

prio:high

🦋 MAILDIR 🦋

the Maildir field describes the directory path starting after the Maildir root directory, and before the /cur/ or /new/ part. so, for example, if there's a message with the file name ~/Maildir/lists/running/cur/1234.213:2,,, you could find it (and all the other messages in that same maildir) with:

maildir:/lists/running

note the starting /. if you want to match mails in the "root" maildir, you can do with a single /:

maildir:/

if you have maildirs (or any fields) that include spaces, you need to quote them, i.e.,

maildir:"/Sent Items"

and once again, note that when using the command-line, such queries must be quoted:

mu find 'maildir:"/Sent Items"'

also note that you should not end the maildir with a /, or it can be misinterpreted as a regular expression term; see aforementioned.

✨ MORE EXAMPLES ✨

here are some simple examples of mu queries; you can make many more complicated queries using various logical operators, parentheses and so on, but in the author's experience, it's usually faster to find a message with a simple query just searching for some words. iykyk 😌

find all messages with both "bee" and "bird" (in any field)

bee AND bird

find all messages with either Frodo or Sam:

Frodo OR Sam

find all messages with the "wombat" as subject, and "capybara" anywhere:

subject:wombat and capybara

find all messages in the "Archive" folder from Fred:

from:fred and maildir:/Archive

find all unread messages with attachments:

flag:attach and flag:unread

find all messages with PDF-attachments:

mime:application/pdf

find all messages with attached images:

mime:image/*

(and beware that on the command-line, you need to put this in quotes or it would expand the *.)

find a messages with the given message-id:

msgid:CAE56pjGU2oNxN-wWku69@mail.gmail.com

find all messages written in Dutch or German with the word "hallo":

hallo and (lang:nl or lang:de)

this is only available if your mu has support for this; see mu info and check for "cld2-support*.

🔍 ANALZYING QUERIES 🔍

despite all the excellent documentation, in some cases it can be non-obvious to understand how mu interprets your query, especially when shell interpretation is involved as well.

for that, you can ask mu to analyze the query -- that is, show how mu interprets the query. we already saw an example of this.

this uses the --analyze option to mu find.

$ mu find subject:wombat AND date:3m.. size:..2000  --analyze
*query:
  subject:wombat AND date:3m.. size:..2000
* parsed query:
  (and (subject "wombat") (date (range "2023-05-30T06:10:09Z" "")) (size (range "" "2000")))
* Xapian query:
  Query((Swombat AND VALUE_GE 4 n64759341 AND VALUE_LE 17 i7d0))

the parsed query is usually the most useful one for understanding how mu interprets your query; it shows the query as mu sees it, in s-expression notation.

in mu4e there is the mu4e-analyze-last-query command, which provides similar information.

🐛 REPORTING BUGS 🐛

please report bugs at https://github.com/djcb/mu/issues.

👑 AUTHOR 👑

Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

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-find(1), mu-info(1), pcre(3)

okay that's the whole mu-query(7) bestie — mu 1.14.2, © 2008–2026 Dirk-Jan C. Binnema. slay 💅✨

📦 where this page comes from