A Comprehensive Guide to Searching in NeoMutt

NeoMutt's power lies in its ability to quickly navigate and manage email without your hands ever leaving the keyboard. Mastering its search and filter capabilities is key to that efficiency. This guide covers everything from basic commands to advanced, combined patterns.

1. Key Search Commands

There are two primary ways to find messages in NeoMutt's index (the list of emails): searching and limiting.

Key	Command	Action
/	Search	Jumps to the next message matching a pattern, keeping all other emails visible.
Esc /	Reverse Search	Jumps to the previous message matching a pattern.
l	Limit / Filter	Filters the index view to only show messages that match the pattern.
n	Next Match	Search for next message that matches the last search or limit pattern.

N toggles a message's "new" flag. Read more about NeoMutt - Index Menu

When to Use Search vs. Limit

• Use Search (/ or Esc /) for Navigation: When you just want to find and jump to a specific email quickly without losing the context of your full mailbox.

• Use Limit (l) for Focus and Bulk Actions: When you need to work with a specific subset of emails. For example, you could limit to all emails from a specific project (l~s "Project X"), tag them all for archival, and then remove the limit.

Tip: To remove a limit and return to the full view, press l and enter the pattern ~A (for "All") or simply enter an empty pattern.

2. Basic Search Patterns

The core of NeoMutt's search is using patterns prefixed with a tilde (~). When you execute a search or limit command, you enter the pattern in the prompt.

Searching Specific Email Parts

The following patterns allow you to target specific parts of an email:

Pattern	Target	Example
~s "expr"	Subject	l~s "meeting"
~b "expr"	Body	/~b "Weekly report"
~B "expr"	Whole Message (headers and body)	l~B "secret-project-code"
~f "expr"	From	l~f "john.doe@example.com"
~t "expr"	To	/~t "support@company.com"
~c "expr"	Cc/Bcc	l~c "marketing"
~L "expr"	List-ID	/~L neomutt.org
~h 'Header: expr'	Header	l~h 'X-Priority:High'

Searching Message Status

You can filter based on flags and status:

Pattern	Description	Example
~N	New Messages marked as "new" (never viewed)	l~N
~U	Unread Messages marked as "unread"	l~U
~O	Old Messages that are neither new nor unread	l~O
~D	Deleted Messages marked for Deletion	l~D
~F	Flagged Messages marked as "flagged" (important)	/~F
~T	Tagged Messages that have been tagged	l~T
~r	Replied Messages you have replied to	l~r
~Q	Queued/Postponed Messages that are postponed	l~Q
~a	Attachements Messages that have attachments	l~a
~d [range]	Date Range Messages within a date range	l~d ">2d" (newer than 2 days)

Read more about NeoMutt - Pattern Modifier

3. Combining Patterns

You can combine multiple patterns using logical operators for complex searches:

Operator	Logic	Example
(space) or &	AND	l~s project ~f client@ (Subject has "project" AND is from "client@")
|	OR	l~s "bug" | ~s "error" (Subject contains "bug" OR "error")
!	NOT	l~U !~f "newsletter" (Unread messages that are NOT from "newsletter")
()	Grouping	l(!~f "mom" & ~a) (Has an attachment AND is NOT from "mom")

Combined Examples

• Limit to unread messages from "John" or "Jane":
  l~U (~f "John" \| ~f "Jane")

• Find all non-deleted emails with "invoice" in the subject or body:
  /!~D (~s "invoice" \| ~b "invoice")

• Search for "invoice" in the subject, body, or from a specific sender:
  /~s invoice | ~b invoice | ~f billing@

• Limit to all unread messages that are NOT from "spam@":
  l~U & !~f spam@

Search Patten Guideline

Here is a simple guideline for constructing NeoMutt search patterns, focusing on the use of quotes and best practices.

The need for quotes depends entirely on whether your search expression contains a space or relies on variable/command substitution.

1. When to Omit Quotes

(The Simple Case)

Omit quotes when your search expression is a single word or a complex Regular Expression (regex) that does not contain any literal spaces.

Scenario	Pattern Example	Explanation
Single Word	/~s project	"project" is treated as one search token.
Simple Regex	l~f ^user@	The regex is evaluated as a single, contiguous string.
Combined Search	l~U&~a	The & is the explicit logical operator, not a space, so grouping isn't needed.

Best Practice: Omit quotes whenever possible for the cleanest, most readable pattern.

2. When to Use Quotes

(Grouping is Required)

Quotes are necessary to ensure that a phrase containing spaces is treated as a single, literal search argument, overriding NeoMutt's default behavior of treating spaces as the logical AND operator.

A. Strong Quoting

(Single Quotes: ') - Preferred for Literal Phrases

Use single quotes when you need to search for a literal phrase that includes spaces. This is the safest default for searching text.

Scenario	Pattern Example	Explanation
Literal Phrase	l~b 'quarterly report'	Forces NeoMutt to search for the exact phrase "quarterly report" (with one space).
Email Address	/~f 'John Smith <john@example.com>'	Groups the full name and email address as one search token.

Best Practice: Use single quotes (') for all multi-word, literal text searches, as this prevents accidental variable expansion.

B. Weak Quoting

(Double Quotes: ") - Required for Dynamic Content

Use double quotes only when you need NeoMutt to interpret (expand) variables or commands inside the search pattern before executing the search.

• Variable Expansion: l~s "Invoice from $USER", The $USER variable is substituted with the current user's name before searching.
• Command Substitution: l~d "<`date -d '1 month ago' +%Y%m%d`", The date command inside the backticks (date -d '1 month ago' +%Y%m%d) is executed, and its output (e.g., 20250914) is inserted into the search string. The resulting search is l~d "<20250914".

WARNING

Note that the last example inside the table could be incorrect and need to be verified again. Read more about Linux CLI.

4. Advanced Tips

Case Sensitivity

By default, NeoMutt's patterns are often case-insensitive. If you need a case-sensitive search, you generally need to use the full regular expression capabilities.

Regular Expressions

All search expressions (expr) are treated as POSIX Extended Regular Expressions (ERE). This allows for very powerful matching.

• Search for subjects that start with "Re:":
  /~s "^Re:"
• Find subjects containing a version number like v1.2.3:
  /~s "v1\.2\.3" (The . is escaped to match a literal period).

Searching by Date

~d [range]

Date Pattern	Description
>DD/MM/YYYY	After a date
<DD/MM/YYYY	Before a date
DD/MM/YYYY-DD/MM/YYYY	Between two dates
>Nd, >Nw, >Nm, >Ny	Newer than N days, weeks, months, years
<Nd, <Nw, <Nm, <Ny	Older than N days, weeks, months, years

Speeding up Body Search

~b, ~B

Searching the body of emails can be slow, especially over an IMAP connection. To dramatically speed this up, NeoMutt can cache message bodies locally.

Add the following to your ~/.config/neomutt/neomuttrc file, creating the directories if they don't exist:

# ~/.neomuttrc

set header_cache = "~/.cache/neomutt/headers"
set message_cachedir = "~/.cache/neomutt/bodies"

The first search in a folder will be slow as it builds the cache, but subsequent searches will be nearly instant.

5. General Best Practices

Practice	Guideline
Prioritize Specificity	Always use the most specific search operator (~s, ~f, ~b) rather than the general whole-message search (~B) for better performance.
Use Parentheses	Use parentheses () for complex logical operations to ensure correct precedence: l~s "report" & (~U ~F).
Enable Caching	If searching the body (~b) of large or remote (IMAP) mailboxes is slow, ensure you have set $message_cachedir in your config for a significant speed boost.