Real Programmers/ Jump Start/ Mutt
Google site:


Essential Info

"Mutt is a small but very powerful text-based mail client for Unix operating systems".

Getting Started

Mutt is based on elm (and written by the same author) so will feel familiar to people who've used elm. Pine users will need a little adjusting (someone write a help sheet for pine -> mutt?).

Mutt's own documentation provides a good introduction in 2.0 Getting Started. This is well worth skim reading, in particular the keystroke tables in each section: 2.1 Moving Around in Menus, early parts of 2.3 Reading Mail - The Index and Pager and 2.4 Sending Mail.

Here are a few keystrokes that I use frequently,


Mutt has the ability to display messages by related discussion ("threads") rather than the more commonly seen (and jumbled) date sent. When reading through unread messages the effect is some topical consistency -- a great boon with high volume mailing lists or personal discussions. See the example .muttrc introduced later which uses set sort=threads

(Internally mutt uses the In-Reply-To: and References: headers which are set automatically when replying by decent mail clients; it falls back by default on Subject:).

The "limit" command

The "limit" command l filters the display of messages. Mutt's documentation doesn't make a big deal of "limit" nor introduces it until well into the manual but it's one of mutt's real gems and is well worth learning early.

For example, paul.makepeace searches on subject, author and email address limiting the display to those that match. make would return at least as many results. All searches are case insensitive, and are regular expressions so ^, $, . (period) etc have special meanings. (Learn about 4.1 Regular Expressions.)

Often this method is enough but it's possible to limit on more specific patterns using a code prefixed with ~ (tilde). Here are some more examples:

Limit examples

  • ~s party : messages with subject containing "party"
  • ~d <2w : messages less than two weeks old. Also: year, month, week, day.
  • ~t paulm : To: matches paulm (useful for sent-mail folders)
  • ~O : old (i.e. unread but not new) messages. ~N is new unread. ~U is unread, i.e. both together.
  • ~p : messages addressed to you (useful if your inbox is bombarded with mailing list or system report activity).
  • ~p ~U : for messages to you you haven't read yet.
  • . : matches everything. In effect, remove the limit.
More patterns in 4.2 Patterns.


The t command tags a message and a * will toggle next to the message in the index page. You can also tag messages using patterns (T) just like limit. Once tagged a large set of commands can operate on the tagged set as a whole by prefixing the keystroke with ; For example ;s saves tagged messages.

Tagging example: deleting en masse

Here is an example that demonstrates a common sequence to delete all emails that contain the subject "work". (Don't follow along unless you actually want to do this :-)
  1. lwork : limit messages to work and visually inspect the results.
  2. Oops, you've seen some have matched on a friend's email address that contains "work". Try again with just subject match: ~s work - better!
  3. T : mutt uses your last expression for a tag-pattern. Since your pattern is fine, press enter.
  4. All messages appear with a * next to them since we're still in a limited view with an identical pattern.
  5. l. : remove the limit, out of curiosity. You see scattered tagged messages.
  6. Delete all those work emails: ;d
  7. Commit the changes with the $ keystroke.
The same effect could be achieved using D ("Delete messages matching") but is not as interactive.

Tagging example: saving mailing list messages

This example shows a way of clearing out your inbox of mailing list messages. When I first subscribe I let them come into my inbox which I read with somewhat more attention than my other non-work folders. After a while I get a sense of the list and then save it somehwere and set up a filter (not using mutt). Sometimes however these lists have no Subject: line I can filter on, nor a useful Sender: line (two header lines mutt has specific pattern support for, ~s and ~e). Here's what I do,
  • Find an example of a mailing list post
  • Switch to view full headers with h
  • Look through to find a non-sender specific header line, e.g.
    Mailing-List: contact mailing-list-help@domain.tld
  • Select this into my clipboard
  • Tag messages using ~B "^paste-clipboard". Note:
    • the use of ~B (search including headers)
    • ^ to tie the match to the beginning of line - this will dramatically speed the search up.
    • " to enclose the pattern so I can have spaces in there, or else mutt will treat the second part as another search pattern.
  • tag (;) save (s) them, ;s=Lists/mailing-list
  • Commit the changes: $
More on tagging in 4.3 Using Tags

Mail Folders

A folder or mailbox is a place where mail is stored. c changes to a particular folder, relative to the directory mutt was started in. Mutt can also be invoked with the -f option to start with a particular folder, e.g. mutt -f ~/mbox

There is no restriction (aside from user permissions) where folders reside although mutt provides for storing them in a known place specified by the folder configuration which defaults to ~/Mail. Folders under this directory can then be referenced by prefixing the name with = so =Lists/mutt-users is mutt-speak for ~/Mail/Lists/mutt-users. This works with -f too: mutt -f =work/realprogrammers

There are other 4.7 Mailbox Shortcuts: notably ! is the user's mail spool (MAIL environment variable) and > is the mbox file.

A handy tip for your .muttrc especially if you have particularly large folders or are operating over a slow connection. The read_inc variable sets how often the read counter is updated. The low default value (10) sprays characters at the terminal, which can really drag.

Automatically checking folders

The mailboxes config tells mutt where to look for folders. When mail arrives there, mutt will dutifully inform you. At which point c (change-folder) will default to the list of folders that have new messages, in the order they appear on the mailboxes line. Space cycles through them.

Example .muttrc

There is a fully annotated example .muttrc with links all over the mutt manual and reference pages.

Further exploration

At this point after reading the example .muttrc and perhaps some config examples from, tackling a linear read of the Mutt Manual should be an approachable task. There are strange aspects to the mutt manual which I've tried to mitigate (e.g. try to find an explanation of a quadoption) but when in doubt Google is a great help: try adding before your query.


All non-user content and code Copyright © 2000-2006 / Paul Makepeace. Comments & feedback welcome!