Previous Next Table of Contents

4. Configuring Mutt

While the default configuration (or ``preferences'') make Mutt usable right out of the box, it is often desirable to tailor Mutt to suit your own tastes. When Mutt is first invoked, it will attempt to read the ``system'' configuration file (defaults set by your local system administrator), unless the ``-n'' command line option is specified. This file is typically /usr/local/share/Muttrc or /usr/local/lib/Muttrc. Next, it looks for a file in your home directory named .muttrc. In this file is where you place commands to configure Mutt.

4.1 Syntax of Initialization Files

An initilization file consists of a series of commands, each on its own line. The hash mark, or pound sign (``#''), is used as a ``comment'' character. You can use it to annotate your initialization file. All text after the comment character to the end of the line is ignored. For example,

my_hdr X-Disclaimer: Why are you listening to me? # This is a comment

Sometimes it is necessary to make the comment character appear in a string. This can be done by putting a backslash (``\'') in front of it.

It is also possible to substitute the output of a Unix command in an initialization file. This is accomplished by enclosing the command in backquotes (``). For example,

my_hdr X-Operating-System: `uname -a`
The output of the Unix command ``uname -a'' will be substituted before the line is parsed. Note that since initialization files are line oriented, only the first line of output from the Unix command will be substituted.

4.2 Creating aliases

Usage: alias key address [ , address, ... ]

It's usually very cumbersome to remember or type out the address of someone you are communicating with. Mutt allows you to create ``aliases'' which map a short string to a full address.

Note: if you want to create an alias for a group (by specifying more than one address), you must separate the addresses with a comma (``,'').

alias muttdude me@cs.hmc.edu (Michael Elkins)
alias theguys manny, moe, jack

4.3 Specify an alternate e-mail address

Usage: alternates address [ address ... ]

When displaying the contents of a mailbox, Mutt attempts to indicate messages which are addressed to you (as opposed to mail from lists). Often times you might receive mail at an address that Mutt doesn't understand as being yours. The alternates command allows you to specify alternate addresses where you receive mail.

If your network is such that you can receive mail at any number of hosts in a subnetwork, it can be burdensome to list all possible addresses. In this case, you can make use of the wildcard character (``*'') to match any possibility. The wildcard character must be the first character in the domain part of the address (the part after the at sign (``@''). For example,

alternates joe@*.bigcompany.com

This example would make any host in the ``bigcompany.com'' domain match.

4.4 Changing the default key bindings

Usage: bind key function menu

This command allows you to change the default key bindings (operation invoked when pressing a key). key is the key you wish to bind. To specify a control character, use the sequence \Cx, where x is the letter of the control character (for example, to specify control-A use ``\Ca''). Note that the case of x as well as \C is ignored, so that \CA, \Ca, \cA and \ca are all equivalent. key does not need to be enclosed in quotes unless it is a space (`` ''). In addition, key may be one of up, down, left, right, pageup, or pagedown to specify the function key of the same name.

function specifies which action to take when key is pressed.

menu specifies in which menu the binding belongs. The currently defined menus are:

4.5 Using color and mono video attributes

If your terminal supports color, you can spice up Mutt by creating your own color scheme. To define the color of an object (type of information), you must specify both a foreground color and a background color (it is not possible to only specify one or the other).

Usage: color object foreground background

object can be one of:

foreground and background can be one of the following:

foreground can optionally be prefixed with the keyword bright to make the foreground color boldfaced (e.g., brightred).

If your terminal does not support color, it is still possible change the video attributes through the use of the ``mono'' command:

Usage: mono <object> <attribute

where attribute is one of the following:

4.6 Ignoring (weeding) unwanted message headers

Usage: [un]ignore pattern [ pattern ... ]

Messages often have many header fields added by automatic processing systems, or which may not seem useful to display on the screen. This command allows you to specify header fields which you don't normally want to see.

You do not need to specify the full header field name. For example, ``ingore content-'' will ignore all header fields that begin with the pattern ``content-''.

To remove a previously added token from the list, use the ``unignore'' command. Note that if you do ``ignore x-'' it is not possible to ``unignore x-mailer,'' for example. The ``unignore'' command does not make Mutt display headers with the given pattern.

``unignore *'' will remove all tokens from the ignore list.

4.7 Mailing lists

Usage: [un]lists address [ address ... ]

Mutt has quite a few nice features for dealing with mailing lists. In order to take advantage of them, you must tell Mutt which addresses belong to mailing lists.

It is important to note that you should never specify the domain name ( the part after the ``@'') with the lists command. You should only specify the ``mailbox'' portion of the address (the part before the ``@''). For example, if you've subscribed to the Mutt mailing list, you will receive mail addressed to ``mutt@cs.hmc.edu''. So, to tell Mutt that this is a mailing list, you would add ``lists mutt'' to your initialization file.

The ``unlists'' command is to remove a token from the list of mailing-lists. Use ``unlists *'' to remove all tokens.

4.8 User defined headers

Usage: my_hdr string

This command allows you to create your own header fields which will be added to every message you send.

For example, if you would like to add an ``Organization:'' header field to all of your outgoing messages, you can put the command

my_hdr Organization: A Really Big Company, Anytown, USA

in your .muttrc.

If you would like to add a header to a single message, you should either set the edit_hdrs variable, or use the edit-headers function (default: ``E'') in the send-menu so that you can edit the header of your message along with the body.

4.9 Setting variables

Usage: [un]set [no]variable [ = value ]

This command is used to set (and unset) configuration variables. There are three basic types of variables: boolean, number and string. boolean variables can be set (true) or unset (false). number variables can be assigned a positive integer value.

string variables consist of any number of printable characters. strings must be enclosed in quotes if they contain spaces or tabs. You may also use the ``C'' escape sequences \n and \t for newline and tab, respectively.

Prefixing a boolean variable with ``no'' will unset it (same as the unset command):

Example: set noaskbcc.

Selecting the sorting method

Usage: sort method

Sets the default mode for sorting messages in the message index (main-menu). method is allowed to be one of the following:

For all modes except ``threads'', you may use the prefix ``reverse-'' to sort in reverse.

Example: sort reverse-date-sent.

Reading initialization commands from another file

Usage: source filename

This command allows the inclusion of initialization commands from other files. For example, I place all of my aliases in ~/.mail_aliases so that I can make my ~/.muttrc readable and keep my aliases private.

If the filename begins with a tilde (``~''), it will be expanded to the path of your home directory.

4.10 Configuration variables

alias_file

Type: string
Default:  /.muttrc

The default file in which to save aliases created by the ``create-alias'' function.

allow_8bit

Type: boolean
Default: unset

Controls whether 8-bit data is converted to 7-bit using either Quoted-Printable or Base64 encoding when sending mail.

askbcc

Type: boolean
Default: unset

If set, Mutt will prompt you for blind-carbon-copy (Bcc) recipients before editing an outgoing message.

askcc

Type: boolean
Default: unset

If set, Mutt will prompt you for carbon-copy (Cc) recipients before editing the body of an outgoing message.

askcopy

Type: boolean
Default: set

If set, Mutt will ask you if you would like to save a copy of your outgoing message.

askdelete

Type: boolean
Default: set

If set, Mutt will confirm that you really want to delete messages when closing a mailbox.

askmove

Type: boolean
Default: set

If the hold variable is set, you will be asked to confirm moving read messages from your spool mailbox to your mbox mailbox.

askpostpone

Type: boolean
Default: set

If set, you will be asked if you would like to postpone your outgoing message if you decide not to send it.

askprint

Type: boolean
Default: set

Controls whether or not Mutt asks for confirmation before printing. This is useful for people (like me) who accidentally hit ``p'' often.

askrecall

Type: boolean
Default: set

When set, you will asked if you would like to recall a postponed message when you elect to compose a new mail message (only if there are messages postponed). Also see postponed

askreplyto

Type: boolean
Default: unset

If set, Mutt will ask you if you want to use the address listed in the Reply-To header field when replying to a message. If you answer no, it will use the address in the From: header field instead. This option is useful for reading a mailing list that sets the Reply-To header field to the list address and you want to send a private message to the author of a message.

attribution

Type: format string
Default: "On %M %N, %n wrote:"

This is the string that will precede a message which has been included in a reply. For a full listing of defined escape sequences (%M, etc.), see the section on hdr_format.

autoedit

Type: boolean
Default: unset

If the edit_hdrs variable is also set, the initial prompt for recipients and subject in the send-menu will be skipped, placing you immediately in your editor.

autoinclude

Type: boolean
Default: unset

If set, Mutt will automatically include a copy of the message you are replying to instead of asking if you want to.

dsn_notify

Type: string
Default: "failure,delay"

If Mutt was compile with support for DSN, this variable sets the request for when notification is returned. The string consists of a comma separated list (no spaces!) of one or more of the following: never, to never request notification, failure, to request notification on transmission failure, delay, to be notified of message delays, success, to be notified of successful transmission.

dsn_return

Type: string Default: "hdrs"

This variable controls how much of your message is returned in DSN messages. It may be set to either hdrs to return just the message header, or full to return the full message.

edit_hdrs

Type: boolean
Default: unset

This option allows you to edit the header of your outgoing messages along with the body of your message.

editor

Type: String
Default: value of environment variable $VISUAL, $EDITOR, or "vi"

This variable specifies which editor to use when composing messages.

folder

Type: String
Default: ~

Specifies where your mailboxes can be found.

force_name

Type: Boolean
Default: unset

When set, Mutt will save outgoing messages in a folder specified by the username of the person you are mailing to. This variable overrides the record variable.

hdr_format

Type: format string
Default: "%M %2N %-15.15L (%6c) %s"

This variable allows you to customize the message index display to your personal taste.

``Format strings'' are similar to the strings used in the ``C'' function printf to format output (see the man page for more detail). The following sequences are defined in Mutt:

%a      address of the author
%c      number of characters (bytes) in the message
%C      current message number
%d      date and time of the message
%L      list-from function
%f      entire From: line (address + real name)
%F      entire From: line, unless from self
%i      message-id of the current message
%l      number of lines in the message
%M      three-letter abbreviation for the month
%m      number of the month (1-12)
%n      real (personal) name of author
%N      number of the day of the month
%s      subject of the message
%S      status of the message ([New], [Deleted], [Flagged], [Tagged])
%T      total number of message in the mailbox
%u      user (login) name of the author
%y      last two digits of the year
%Y      year

header

Type: boolean
Default: unset

When set, this variable causes Mutt to include the full header of the message you are replying to into the edit buffer.

hold

Type: boolean
Default: set

If set, this causes Mutt not to move read messages from your spoolfile file to your mbox file.

in_reply_to

Type: format string
Default: "%i; from \"%n\" on %d"

This specifies the format of the In-Reply-To: header field added when replying to a message.

keep_empty

Type: boolean
Default: unset

By default, Mutt will remove any mailboxes which contain zero messages. This variable overrides that default and causes Mutt to never remove mailboxes.

keepsave

Type: boolean
Default: unset

If set, Mutt will not delete messages which have been saved to another folder. This causes the ``save'' and ``copy'' commands to become identical.

localsignature

Type: string
Default: none

The filename of your signature file which should be copied into the message buffer when the recipients are all local. Note: setting this variable overrides the value of signature.

mark_old

Type: Boolean
Default: set

Controls whether or not Mutt makes the distinction between new messages and old unread messages. By default, Mutt will mark new messages as old if you exit a mailbox without reading them. The next time you start Mutt, the messages will show up with an "O" next to them in the index menu, indicating that they are old. In order to make Mutt treat all unread messages as new only, you can unset this variable.

When set, this causes the jump-new function to position the cursor on the first new message, which may not be the first unread message. If unset, jump-new always moves to the first unread message, because the distinction between unread and new is ignored.

mbox

Type: String
Default: +inbox

This specifies the folder into which read mail in your spoolfile folder will be appended.

metoo

Type: Boolean
Default: unset

If set, Mutt will not remove your address from the list of recipients when replying to a message.

pager

Type: string
Default: internal

This variable specifies which pager you would like to use to view messages.

pager_fmt

Type: format string
Default: "%S %C/%T: %-20.20n %s"

This variable controls the format of the one-line message ``status'' displayed before each message in either the internal or an external pager. The valid seqeunces are listed in the hdr_format section.

pager_stop

Type: boolean
Default: unset

When set, the internal-pager will not move to the next message when you are at the end of a message and invoke the next-page function.

pgp

Type: string
Default: system dependent

This variable allows you to override the compile time definition of where the PGP binary resides on your system.

pgp_autosign

Type: boolean
Default: unset

Setting this variable will cause Mutt to always attempt to PGP/MIME sign outgoing messages. This can be overriden by use of the pgp-menu, when signing is not required or encryption is requested as well.

pointnew

Type: boolean
Default: set

This variable controls whether mutt will position you at the first new (or unread) message in the mailbox when the mailbox is first opened.

popdelete

Type: boolean
Default: unset

If set, Mutt will delete successfully downloaded messages from the POP server when using the fetch-mail function. When unset, Mutt will download messages but also leave them on the POP server.

pophost

Type: string Default: none

The name or address of your POP3 server.

popuser

Type: string Default: login name on local system

Your login name on the POP3 server.

post_indent_str

Type: format string
Default: none

Similar to the attribution variable, Mutt will append this string after the inclusion of a message which is being replied to.

postponed

Type: string
Default: ~/postponed

Mutt allows you to indefinitely postpone sending a message which you are editing. When you choose to postpone a message, Mutt saves it in the folder specified by this variable. Also see the askpostpone variable.

print

Type: string
Default: lpr

This specifies the command that should be used to print messages.

prompt_after

Type: boolean
Default: set

If you use an external pager, setting this variable will cause Mutt to prompt you for a command when the pager exits rather than returning to the index menu. If unset, Mutt will return to the index menu when the external pager exits.

quote_regexp

Type: string
Default: "ˆ>|#:} "

A regular expression used in internal-pager to determine quoted sections of text in the body of a message.

readmsginc

Type: number
Default: 10

If set to a value greater than 0, mutt will display which message it is currently on when reading a mailbox. The message is printed after readmsginc messages have been read (e.g., if set to 25, Mutt will print a message when it reads message 25, and then again when it gets to message 50). This variable is meant to indicate progress when reading large mailboxes which may take some time.

When set to 0, only a single message will appear before the reading the mailbox.

Also see the writemsginc variable.

realname

Type: string
Default: GCOS field from /etc/passwd

This variable specifies what "real" or "personal" name should be used when sending messages.

record

Type: string
Default: none

This specifies the file into which your outgoing messages should be appended. This is meant as the primary method for saving a copy of your messages, but another way to do this is using the my_hdr command to create a Bcc: field with your email address in it.

remotesignature

Type: string
Default: none

The filename of the signature file which should be appended to the message buffer when the destination of the message is a remote host. Note: setting this variable overrides the value of signature.

reverse_alias

Type: boolean
Default: unset

This variable controls whether or not mutt will display the "personal" name from your aliases in the index menu if it finds an alias that matches the message's sender. For example, if you have the following alias:

alias juser abd30425@somewhere.net (Joe User)

and then you receive mail which contains the following header:

From: abd30425@somewhere.net

It would be displayed in the index menu as ``Joe User'' instead of ``abd30425@somewhere.net.'' This is useful when the person's e-mail address is not human friendly (like Compu$erve addresses).

sendmail

Type: string
Default: /usr/lib/sendmail

This variable specifies the path to the program used to deliver your outgoing messages. This allows you to insert a filter between Mutt and sendmail, if so desired.

shell

Type: string
Default: retrieved from passwd file

Command to use when spawning a subshell.

sigdashes

Type: boolean
Default: set

If set, a line containing ``-- '' will be inserted before your signature. It is strongly recommended that you not unset this variable unless you ``signature'' contains just your name. The reason for this is because many software packages use ``-- '' to detct your signature. For example, Mutt has the ability to hilite the signature in a different color in the internal-pager.

signature

Type: string
Default: ~/.signature

Specifies the filename of your signature, which is appended to all outgoing messages. Note: This variable is overridden by both the remotesignature and localsignature commands.

spoolfile

Type: string
Default: most likely /var/mail/$USER or /usr/spool/mail/$USER

If your spool mailbox is in a non-default place where Mutt cannot find it, you can specify its location with this variable. Mutt will automatically set this variable to the value of the environment variable $MAIL if it is set.

timeout

Type: number
Default: 600

This variable controls the number of seconds Mutt will wait for a key to be pressed in the main menu before timing out and checking for new mail. A value of zero or less will cause Mutt not to ever time out.

status_format

Type: string
Default: "---Mutt: %f [%M/%m msgs, %n new, %l bytes]---(%s)------------..."

Controls the format of the status line displayed in the main-menu. This string is similar to hdr_format, but has its own set of printf()-like sequences:

%h      local hostname
%f      the full pathname of the current mailbox
%l      size (in bytes) of the current mailbox
%m      the number of messages in the mailbox
%M      the number of messages shown (i.e., which match the current limit)
%n      number of new messages in the mailbox
%p      number of postponed messages
%s      current sorting mode
%t      number of tagged messages
%v      Mutt version string

It is also possible to optionally print a variable if it is non-zero. For example, you might want to display a message about how many new messages there are only if there actually are new messages. To optionally print a variable, use:

%?...?

Immediately after the first question mark (?) you should place the normal sequence from the above table (without the %). You may then add an optional string to it. Here are some examples:

%?n new? %?t tagged? %?m shown?

This will print ``N new'' if ``N'' is not zero, otherwise it will ignore everything between the question marks that surround it. The same goes for the other examples on that line.

status_on_top

Type: boolean
Default: unset

Setting this variable causes the status_format to be displayed on the first line of the screen rather than near the bottom. This variable has no effect when xterm_mouse is set.

tmpdir

Type: string
Default: /tmp

This variable allows you to specify where Mutt will place its temporary files needing for displaying and composing messages.

tochars

Type: string
Default: " +TCF"

Controls the character used to indicate mail addressed to you. The first character is the one used when the mail is NOT addressed to your (default: space). The second is used when you are the only recipient of the message (default: +). The third is when your address appears in the TO header field, but you are not the only recipient of the message (default: T). The fourth character is used when your address is specified in the CC header field, but you are not the only recipient. The fifth chacter is used to indicate mail that was sent by you.

web_browser

Type: string
Default: unset

Command to start a textmode WWW browser on a URL. This command will be invoked by the browse-url function. The sequence ``%s'' is replaced by the URL. If no ``%s'' is given, the URL will be appended to the command.

Example: set web_browser="lynx %s"

web_xbrowser

Type: string
Default: unset

If the environment variable DISPLAY is set, Mutt will assume you are running X-windows and use this command to display URL when the browse-url function is invoked. If DISPLAY is not set, browse-url will invoke the command named by web_browser.

Example: set web_xbrowser="netscape -remote 'openURL(%s)'"

writemsginc

Type: number
Default: 10

When writing a mailbox, a message will be printed every writemsginc messages to indicate progress. If set to 0, only a single message will be displayed before writing a mailbox.

Also see the readmsginc variable.

xterm_mouse

Type: boolean
Default: unset

This variable controls whether or not Mutt will take control of interpreting mouse events inside an xterm. This allows you to use a ``toolbar'' inside of Mutt. Note: you can still use the normal xterm cut and paste operations using the <SHIFT> key.


Previous Next Table of Contents