mutt overview

From now on, this guide is going to assume that you have mutt installed locally, start by typing mutt in your console and hit enter. You may get a couple of warnings straight away; Don’t worry, let mutt create a ~/Mail folder in your home directory and don’t panic if there is no spoolfile for your username - This won’t be created until you actually receive some mail.

The index viewer

When you launch mutt, the first thing you see is a screen with a list of email messages. This initial menu is called the index.

These messages are in a default mailfolder, often called the mailspool, that you can think of as your ‘inbox’. Use the k and j keys on your keyboard to move the highlighted cursor up and down the list of messages.

The pager

If you are in the index and you want to view the contents of an email, hit the enter key on your keyboard, this will take you from the index to the pager. Mutt’s built-in pager is just a scrolling text viewer like the unix programs ‘more’ and ’less’, use the backspace and enter keys to scroll up and down the email. Most of the commands that can be used in the index can also be used in the pager.

Quit the pager and return to the index by pressing the q key.

The attach ment viewer

email has a structure that can include attached parts such as files as well as plain text messages. From the index , press the v key to view the attach menu where you can see the ‘mime-structure’ of the email displayed as a threaded list.

If there is more than one part to a message, you can use the k and j keys to move up and down the list and the enter key to view any item. If the attachment can be viewed by mutt’s internal pager as plain text then it will. If not, mutt will try and launch a suitable external viewer, and wait for it to finish.

Quit the attach ment viewer by pressing the q key on your keyboard

The file browser

To change from your mailspool to a different mailfolder, press the c key. You can now either type in the location of the folder you want to open, or press the ? key to open the file browser. Use the k and j keys to select the folder you want to switch-to and open it by hitting the spacebar.

Tab completion

A faster alternative to the file browser can be to take advantage of mutt’s ’tab-completion’. Whenever you need to change folders, just hit c , type the first character or two of the folder’s name and hit the tab key. Mutt will show you all the available options or simply fill in the rest of the name automatically.

Mutt supports tab completion everywhere, whether it’s for files, addresses or even setting configuration options. This along with features like pervasive use of regular-expressions for pattern matching and command histories make mutt very fast to use compared with a mouse-oriented mailer.

The editor

In the index or pager views, hit the r key to reply to a message or the m key to create a new one. Mutt will prompt for the To: address and the Subject: line, then launch your favourite text editor (defined by your $EDITOR environmental variable). Type away, when you save and exit, you are done.

The compose menu

After the editor , mutt drops you into the compose menu, here you can fine-tune your message headers, change the encoding, add file attachments or simply hit the y key to say yes and send your email on its way.

The muttrc file

Mutt doesn’t have a configuration interface, there is no properties menu or setup wizard. All configuration options can be changed at any time by typing a : followed by the relevant command. For example :unset help turns off the handy keyboard command hints at the top of the screen. To turn those hints back on, press up-arrow to retrieve the last command and change it so it says :set help.

If you can’t remember the command you want to use, there is always tab-completion to help you.

You don’t have to type all your preferred configuration commands each time you run mutt, you can save them in a file which is loaded every time the program starts up. This configuration file needs to exist in your home directory, it has to be called either ~/.muttrc or ~/.mutt/muttrc.

A commented starter muttrc is included with the distribution as contrib/sample.muttrc-starter ; if mutt came from your system packages, look in /usr/share/doc/mutt/. It is a good place to begin, and it covers most of what you will want in your first week. You can also base yours on somebody else’s, such as Roland’s .muttrc.

The sidebar

Mutt can show a persistent list of your mailboxes down the left of the screen, with unread counts, much like a graphical mailer. This used to be a third-party patch; it has been part of mutt since version 1.7 and is enabled at runtime:

set sidebar_visible

On its own that only draws the list; you also need keys to move around it. Three functions do the work, and these are the bindings the shipped example uses:

bind index,pager \Cp sidebar-prev
bind index,pager \Cn sidebar-next
bind index,pager \Co sidebar-open

sidebar-prev and sidebar-next move the highlight up and down the list without leaving the mailbox you are reading, and sidebar-open opens the one you have landed on. The complete example is in contrib/sample.muttrc-sidebar , and every setting is listed in the sidebar section of the manual.

Context sensitive help

This overview has mentioned just a small number of basic mutt keyboard commands. Mutt has many more commands than you would want to remember, so when you are stuck, hit the ? key and mutt will present a list of all the key-bindings relevant to the current view.

Other sources of help

The mutt manual contains all the reference information you need to run and configure mutt. It also includes a complete step-by-step overview of mutt features, so read it.

You can read the full manual at any time by hitting the f1 key on your keyboard; most distributions ship a pre-set macro that opens the local text version in the ’less’ pager.

If this overview has confused you, try one of the other introductions that cover the same ground: Linda Harden’s Learning Mutt or Norm Matloff’s Introduction to mutt. Both are old but the basics have not changed. For configuration recipes and current packaging notes, the Arch Wiki mutt page is the most useful thing on the web, whatever distribution you run.

The mutt wiki and the mutt FAQ should answer most of the questions you have. If not, you can subscribe to one of the mutt mailing lists - mutt-users is still active and still helpful - or ask in the #mutt channel on Libera Chat.

Bugs and feature requests go to the mutt project on GitLab, which is also where the source lives.

Last updated 31 August 2026.