From ArchWiki
Jump to navigation Jump to search

Mutt is a text-based mail client renowned for its powerful features. Though over 2 decades old, Mutt remains the mail client of choice for a great number of power-users.






Install the mutt package. Alternatively consider using the #NeoMutt package.

Optionally install external helper applications for an IMAP setup, such as isync, OfflineIMAP, or msmtp.

Or (if using POP3) getmail, fetchmailAUR or fdm and procmail.

Note: About authentication setups:
  • If you just need the methods LOGIN and PLAIN, these are satisfied with the dependency libsasl


Tango-go-next.pngThis article or section is a candidate for moving to NeoMutt.Tango-go-next.png

Notes: Is it a drop-in replacement for mutt? Do all configurations on this page apply to it as well? (Discuss in Talk:Mutt#Neomutt)

The NeoMutt project aims to bring together all the patches for Mutt. It adds a large set of features. Lots of old Mutt patches have been brought up-to-date, tidied and documented.

While there are many different packages of mutt in the AUR, each of them providing another set of patches, NeoMutt aims to replace them in the future by implementing appropriate compile options.

NeoMutt can be installed with the neomutt package or alternatively from the AUR at neomutt-gitAUR for the development version.


This section covers #IMAP, #POP3, #Maildir and #SMTP configuration.

Mutt will, by default, search six locations for its configuration file; ~/.muttrc, ~/.mutt/muttrc, and $XDG_CONFIG_HOME/mutt/muttrc, first with -MUTT_VERSION appended, then without. Any of these locations will work. In case you decide to put the initialization file somewhere else, use $ mutt -F /path/to/.muttrc. You should also know some prerequisite for Mutt configuration. Its syntax is very close to the Bourne Shell. For example, you can get the content of another configuration file:

source /path/to/other/config/file


set editor=`echo \$EDITOR`


set my_name = "John Doe"


Native IMAP support

The mutt package is compiled with IMAP support. At the very least you need to have four lines in your muttrc file to be able to access your mail.

set imap_user=USERNAME

If unset, the password will be prompted for.

set imap_pass=SECRET




set folder=imaps://


set folder=imaps://

instead, where your account is This way it will be possible to distinguish the different folders. Otherwise it would lead to authentication errors.


The spoolfile is the folder where your (unfiltered) e-mail arrives. Most e-mail services conventionally name it INBOX. You can now use '=' or '+' as a substitution for the full folder path that was configured above. For example:

set spoolfile=+INBOX

Any IMAP folders that should be checked regularly for new mail should be listed here:

mailboxes =INBOX =family
mailboxes imaps:// imaps://


set imap_check_subscribed


If you do not set this variable, the spoolfile will be used by default. This variable is also important for the #Sidebar.



set folder      = imaps://
set imap_user   =
set imap_pass   = your-imap-password
set spoolfile   = +INBOX
mailboxes       = +INBOX

# Store message headers locally to speed things up.
# If hcache is a folder, Mutt will create sub cache folders for each account which may speeds things up even more.
set header_cache = ~/.cache/mutt

# Can be the same folder as header_cache.
set message_cachedir = "~/.cache/mutt"

set postponed = +[Gmail]/Drafts

# Allow Mutt to open a new IMAP connection automatically.
unset imap_passive

# Keep the IMAP connection alive by polling intermittently (time in seconds).
set imap_keepalive = 300

set mail_check = 120

External IMAP support

While IMAP support is built into Mutt, it does not download mail for offline use. It is possible to use an external application such as OfflineIMAP or isync to download your emails to a local folder which can then be processed by Mutt.

Consider using applications such as spamassassin or imapfilterAUR to sort mail.


The mutt package is compiled with POP3 support, which is configured via the pop_* variables as described in muttrc(5).

Alternatively, it is possible to use external programs to fetch mail using POP3. One popular option is to use getmail for retrieving and procmail for filtering the mail.



set mbox_type=Maildir
set folder=~/mail
set spoolfile=+/
set header_cache=~/.cache/mutt






set record = +Sent

Gmail automatically saves sent e-mail to +[Gmail]/Sent, so we do not want duplicates.

unset record

Native SMTP support

The mutt package is compiled with SMTP support.

For example:

set my_pass='mysecretpass'
set my_user=myname

set realname = 'Your Real Name'
set from = your-email-address
set use_from = yes

set ssl_force_tls = yes



You may need to tweak the security parameters. If you get an error like SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol, then your server probably uses the SMTP instead of SMTPS.


There are other variables that you may need to set. For example for use of STARTTLS:

set ssl_starttls = yes

If your server uses the LOGIN authentication method you might need to specify this explicitly, despite the manual's claim that all methods are tried by default:

set smtp_authenticators = "login"

See muttrc(5) for more information.

External SMTP support


The sendmail variable in your muttrc determines the program and arguments used to deliver mail in mutt. Any additional arguments must be interpreted by the program as recipient addresses.

For example, if using msmtp:

set realname='Disgruntled Kangaroo'

set sendmail="/usr/bin/msmtp"

set edit_headers=yes
set folder=~/mail
set mbox=+mbox
set spoolfile=+inbox
set record=+sent
set postponed=+drafts
set mbox_type=Maildir

mailboxes +inbox +lovey-dovey +happy-kangaroos

Sending mails from Mutt

Now, startup mutt:


$ export EDITOR=your-favorite-editor
$ mutt


set editor=your-favorite-editor


Warning: If at this point you press q by accident, Mutt will ask you Postpone this message? ([yes]/no). This is really asking whether you want to save the message you just wrote. If you press "n" (perhaps because you want to edit the message again) the message will be permanently deleted. When using Mutt, always remember that "Postpone this message?" really means "Save this message?".

Multiple accounts


Well all you need is to write account-specific parameters to their respective files and source them. All the IMAP/POP3/SMTP configuration for each account should go to its respective folder.


Mutt can handle this thanks to one of its most powerful features: hooks. Basically a hook is a command that gets executed before a specific action. There are several hooks available. For multiple accounts, you must use account-hooks and folder-hooks.

  • Account-hooks will run a command every time Mutt calls a function related to an account, like IMAP syncing. It does not require you to switch to any folder.

Hooks take two parameters:

account-hook [!]regex command
folder-hook [!]regex command


Let us give a full example:

## General options
set header_cache = "~/.cache/mutt"
set imap_check_subscribed
set imap_keepalive = 300
unset imap_passive
set mail_check = 60
set mbox_type=Maildir

source "~/.mutt/work"

source "~/.mutt/personal"
folder-hook * 'source ~/.mutt/personal'
folder-hook * 'set realname="Bob"'
## Receive options.
set imap_pass=****
set folder = imaps://
set spoolfile = +INBOX
set postponed = +Drafts
set record = +Sent

## Send options.
set realname='User X'
set hostname=""
set signature="John Doe"
# Connection options
set ssl_force_tls = yes
unset ssl_starttls

## Hook -- IMPORTANT!
account-hook $folder "set imap_pass=****"




## Shortcuts



Passwords management

Keep in mind that writing your password in .muttrc is a security risk. One solution is to always enter the password manually, but this becomes cumbersome.

An alternative solution is to encrypt your password with GnuPG in an encrypted file. Setup your own keypair if you have not done so already. Create a file in a tmpfs with the following contents:

set my_pass = "password"
Note: Remember that user defined variables must start with my_.

Then encrypt this file, setting yourself as the recipient and move it into an accessible location. In this example the encrypted file resides at $HOME/.my-pwds.gpg.

In your mutt configuration file add the following before any account:

source "gpg -dq $HOME/.my-pwds.gpg |"

This decrypts the file quietly and sets the variable my_pass in this example. This can be used in any variable after it has been source. For example:

set imap_pass=$my_pass


Security concern

If enter-command is available from the UI, it is possible to see the password unencrypted, which may be undesired if anybody else than you has access to your session while Mutt is running. You may want to disable it for this reason. As a consequence, every command that the user intends to use must be bound to a key in advance, otherwise it will never be accessible.

 bind generic,alias,attach,browser,editor,index,compose,pager,pgp,postpone ':' noop

Tips and tricks

Guides to get you started with using and customizing Mutt:

If you have any Mutt specific questions, feel free to ask in the IRC channel.

Key bindings

The default key bindings are quite far from the more common Emacs-like or Vi-like bindings. You can customize them to your preference. Mutt has a different set of bindings for the pager, the index, the attachment view, etc. Thus you need to specify which map you want to modify when you bind a key. You can review the list of commands and key bindings from Mutt's help page (default key: ?). Example of Vi-like bindings:

bind pager j next-line
bind pager k previous-line
bind attach,index,pager \CD next-page
bind attach,index,pager \CU previous-page
bind pager g top
bind pager G bottom
bind attach,index g first-entry
bind attach,index G last-entry


Encrypt and sign mail (GnuPG)

To start encrypting mail in mutt using GnuPG copy /usr/share/doc/mutt/samples/gpg.rc to your mutt configuration folder (e.g. to ~/.mutt/gpg.rc). Then append the following to your mutt configuration file (e.g. ~/.mutt/mutrrc):

source ~/.mutt/gpg.rc

Most encryption options are then available by pressing p in the compose view.

See the pgp_* and crypt_* options in muttrc(5).

E-mail character encoding

When using Mutt there are two levels where the character sets that must be specified:

  • Mutt will then check the e-mail and determine which encoding is the more appropriate according to the priority you specified in the send_charset variable. Default: "us-ascii:iso-8859-1:utf-8".


To avoid this behaviour, set the variable in your muttrc:

set send_charset="us-ascii:utf-8"

or even

set send_charset="utf-8"


Custom mail headers



set edit_headers=yes



unmy_hdr *


unset use_from
unset use_domain
unset user_agent


my_hdr <FIELD>: <VALUE>



## Extra info.
my_hdr X-Info: Keep It Simple, Stupid.

## OS Info.

## This header only appears to MS Outlook users
my_hdr X-Message-Flag: WARNING!! Outlook sucks

## Custom Mail-User-Agent ID.

Signature block


set signature="path/to/sig/file"
Random signature

You can use fortune (package fortune-mod) to add a random signature to Mutt.


set signature="fortune pathtofortunefile|"


Compose and send from command line


Send a message:

mutt -s "Subject" < /var/log/somelog

Send a message with attachment:

mutt -s "Subject" -a somefile < /tmp/sometext.txt

Compose HTML e-mails


This is normal text<br>
<b>This is bold text</b>



Display another email while composing



mutt -R


Note: When changing folders (with c or y) the read-only mode is not preserved. Instead Esc c has to be used.
Tip: This solution calls for a bit of typing, so it is suitable to bind the following command to a keyboard shortcut:
$TERMINAL -e mutt -R
where $TERMINAL is your terminal.


You can install muttprintAUR for fancier printing quality. In your muttrc file, insert:


Viewing content

Viewing URLs in a web browser



Then install the urlviewAUR package.

Create a .urlview in $HOME and insert the following:

COMMAND <your-browser> %s



COMMAND luakit -n %s 2>/dev/null


Note: urlview has a few deficiencies (e.g. the inability to handle certain email encodings) and is fairly feature-bare (e.g. it does not provide context for links it finds). There are a couple alternatives that do better. One, which can handle all email encodings and provides link context, is Another, which can also provide link context but cannot handle all email encodings, is urlscan-gitAUR. Both are drop-in replacements for urlview, though extract_url has features which benefit from additional configuration changes.

Viewing HTML

It is possible to pass the html body to an external HTML program and then dump it, keeping email viewing uniform and unobtrusive. Three programs are described here: lynx, w3m and elinks (make sure the selected package is installed).


text/html; lynx -assume_charset=%{charset} -display_charset=utf-8 -dump %s; nametemplate=%s.html; copiousoutput

or, in case of w3m,


or, in case of elinks,

text/html; elinks -dump ; copiousoutput;

Edit ~/.muttrc and add the following,

set mailcap_path 	= ~/.mutt/mailcap

To automatically open HTML messages in lynx, w3m or elinks add this additional line to the muttrc:

auto_view text/html

The beauty of this is, instead of seeing an html body as source or being opened by a separate program, in this case lynx, you see the formatted content directly, and any url links within the email can be displayed with Ctrl+b, assuming you have urlviewAUR installed.


alternative_order text/plain text/html


 macro attach 'V' "<pipe-entry>iconv -c --to-code=UTF8 > ~/.cache/mutt/mail.html<enter><shell-escape>$BROWSER ~/.cache/mutt/mail.html<enter>"

If $BROWSER is firefox, then set intl.charset.fallback.utf8_for_file to true in about:config as described in [1] to ensure non-ASCII characters in the HTML page are displayed correctly.

Filtering the message view



To view all flagged messages, use


To view all unread messages that are either of size ≥1MB or from johndoe, use

~U (~z 1M- | ~f johndoe)

All possible patterns are listed in the official manual.

Conversation grouping

The default sort order is by date. Use the sort-mailbox command (default key: o) to change the sorting option. You can group e-mails by conversation/thread, in which case you can define how to sort threads and how to sort within a thread.

In the following example, threads are sorted according to the date of their last e-mail.

set sort=threads
set sort_aux=last-date-received

Configuring editors to work with mutt


au BufRead /tmp/mutt-* set tw=72
augroup filetypedetect
  " Mail
  autocmd BufRead,BufNewFile *mutt-*              setfiletype mail
augroup END
set tmpdir="~/.tmp"
  • To reformat a modified text see the Vim context help
:h 10.7

GNU nano

nano is another nice console editor to use with Mutt.


 set fill 72
 set breaklonglines

If you do not want to limit the width of text globally, you can pass the column number as an argument to the hard-wrap option in your muttrc file, e.g.:

 set editor="nano -r 72 -b"


 set editor="nano +7"



;; Mutt support.



Display settings


Append the contents of /usr/share/doc/mutt/samples/colors.linux to your .muttrc file, or copy and source it. Then adjust to your liking.


Alternatively, you can source any file you want containing colors (and thus act as a theme file). See [2] for a theme example.

Index Format



See the Mutt Reference, strftime(3) and printf(3) for more details.

Display recipient instead of sender in "Sent" folder view

By default Mutt uses the %L format string in the index_format variable, which will display:

  • "To <list-name>", if an address in the "To:" or "Cc:" header field matches an address defined by the user's subscribe command.
  • Otherwise it displays the author name, or recipient name if the message is from you.

If you use multiple email addresses in the same mailbox, make sure to configure the alternates variable, so that Mutt knows which messages were from you.

alternates    ^me@example.COM$ ^me@example.NET$ ^example@archlinux.ORG$

Variable column width



set my_index_format_post=' (%-4.4c) %?M?<%M> ?%-$my_col_subject.${my_col_subject}s"'

folder-hook .*[sS]ent.* "$my_index_format_pre"t"$my_index_format_post"
folder-hook ! .*[sS]ent.* "$my_index_format_pre"F"$my_index_format_post"

We must set the variables my_col_from and my_col_from from within the hooks. Otherwise, the column values will not get re-computed.

We can add a binding to force re-computing the index format without changing folder:

macro index,pager \CL "<enter-command>$my_index_format_pre"F"$my_index_format_post<enter><redraw-screen>"


Example settings for a sidebar are in /usr/share/doc/mutt/samples/sample.muttrc-sidebar, including keybindings. Copy, edit, and source that file in your mutt configuration file. Be sure to change set sidebar_visible = yes.

Append the following in order to toggle the sidebar visibility:

bind index,pager B sidebar-toggle-visible

Note that with the mailboxes option, folders appear in the order they were set to mailboxes if you do not use the sidebar_sort_method option.

Tip: To add a separator between different mailboxes, add a fake folder to the list of folders For example add: mailboxes "+-- My mailbox -----------"

Display the index above the pager view

Set the following variable in your muttrc:

set pager_index_lines=10

Contact management

Address aliases


  • The longname is optional. It may be several words.

It is quite simple indeed. Add this to .muttrc:

set alias_file = "~/.mutt/aliases"
set sort_alias = alias
set reverse_alias = yes
source $alias_file


  • reverse_alias if set to yes mutt will display the "personal" name from your aliases in the index menu if it finds an alias that matches the message's sender.


There are two ways to create aliases:

  • Edit the alias_file manually. The syntax is really simple:
alias nickname Long Name <my-friend@domain.tld>




## Abook
bind editor        <Tab> complete-query



Goobook allows you to search your Google contacts from the command line or from within Mutt and can be installed with the goobook-gitAUR package.

Before using goobook you must configure ~/.goobookrc. To generate the default template:

$ goobook config-template > ~/.goobookrc

See ~/.goobookrc for configuration options. At a minimum, you will need to enter your email and password.

Note: If you have two-step verification enabled with the Google account, you may need to generate an application password.

If you want to use Goobook instead of aliases, remove any alias configuration in .muttrc and add:

## GooBook
set query_command="goobook query '%s'"
macro index,pager a "<pipe-message>goobook add<return>" "add sender to google contacts"
bind editor <Tab> complete-query

When composing an email message within mutt, Tab will now search your Google contacts. While viewing messages a will add the sender to Google contacts.


khard is a command-line addressbook that uses locally-stored carddav address book entries. You can use vdirsyncer to sync those with CardDAV servers.

The integration in mutt is similar to abook, see khard documentation.

Manage multiple sender accounts

If you use multiple sender accounts, you can automatically associate a specific sender account with a recipient. mutt-vidAUR scans sent emails for the most recent "From" details associated with specific recipients, saving these in a file for mutt to source. The next time you email this recipient, mutt will automatically invoke a send-hook with the same email address and real name that you used previously. See mutt-vid's homepage for more details.

Request IMAP mail retrieval manually


bind index "^" imap-fetch-mail

Avoiding slow index on large (IMAP) folders due to coloring


Use folder-hook for only highlighting in, for example, the inbox (if you manage to empty your mailbox efficiently):


Speed up folders switch

Add this to your .muttrc:

set sleep_time = 0

Archive treated e-mails



Migrating mails from one computer to another



Default folder for saving attachments

By default Mutt will save attachments to the folder it was started from. If you want to always set the default destination to ~/attachments, you can create the following alias, which launches Mutt in this folder:

alias mutt='cd ~/attachments && mutt'

Pager behavior

Show context lines when going to next page:

set pager_context=3

Stop at the end instead of displaying next mail:

set pager_stop=yes

Fast reply

By default Mutt will ask to confirm the recipient and the subject when you reply to an e-mail. It will also ask if you want to include the original mail in your answer. If you assume you will always stick to the default values, you can set up Mutt to skip these questions:

set fast_reply=yes
set include=yes

You can still edit the recipient and the subject before sending.

Ignore own e-mail addresses from group-reply

Mutt will include your e-mail address(es) in the recipient list when you group-reply to a mail you were CC'ed. You can ask Mutt to ignore some addresses with:

alternates mail1@server1|mail2@server2|...

IMAP message cache

When using the built-in IMAP support, e-mails are fetched in memory by default. Retrieving a big e-mail several times will download it from your IMAP server that many times.

Alternatively, you can ask Mutt to store all fetched messages on disk:

set message_cachedir=~/.cache/mutt/messages

(The folder must exist.) This will make any future retrieval instantaneous, even with big attachments.

If you want to purge the cache from its oldest e-mails exceeding a limit of, say, 50MB, you can use a script like the following:


## In KB.

cd "$1" 2>/dev/null
[ $? -ne 0 ] && exit

[ $(du -s . | cut -f1 -d'	') -lt $CACHE_LIMIT ] && exit
while IFS= read -r i; do
	rm "$i"
done <<EOF
$(find . -type f -exec ls -rt1 {} +)

and call it on startup:

set message_cachedir=~/.cache/mutt/messages
source "~/.mutt/ '$message_cachedir'|"


Backspace does not work in Mutt


  • Either rebind the key in .muttrc
bind index,pager ^? previous-line


  • Or fix your terminal:
$ infocmp > termbs.src


$ tic -x termbs.src

The change-folder function always prompt for the same mailbox



This is certainly because you are using macros like this one:



Either use the sidebar or set another macro:




set smtp_url=smtps://$imap_user:$


Character encoding problems

If you are having problems with character encoding, first read this section in the Mutt wiki.

If Chinese text is still garbled, it may help to decode with GBK even when GB2312 is specified in the header. You can do this with iconv by adding the following to your mailcap file:

text/plain; iconv -f gbk -t utf-8 %s; test=echo "%{charset}" | grep -ic "gb2312"; copiousoutput;

and enabling it by adding a line to your .muttrc:

auto_view text/plain

For HTML emails, you can edit the relevant line of your mailcap by replacing %{charset} with $(echo %{charset} | sed s/gb2312/gbk/I), for example:

text/html; w3m -dump -I $(echo %{charset} | sed s/gb2312/gbk/I) %s; nametemplate=%s.html; copiousoutput

Unable to login with GMail

Gmail disables access from apps it considers less secure, including mutt. You can enable access by following the instructions here

Not possible to open too long URLs with urlview

Too long URLs are not parsed correctly, because urlview does not decode text (see [3]). You can let mutt decode the e-mails instead. Replace the line for opening urlview with the following code:

macro index \cb "\
:set my_tmp_pipe_decode=\$pipe_decode\n\
:set pipe_decode\n\
:set pipe_decode=\$my_tmp_pipe_decode\n\
:unset my_tmp_pipe_decode\n" \
'call urlview to extract URLs out of a message'



  • The mutt and muttrc man pages.

See also