Neomutt Beginner Tutorial

“All email clients suck, this one just sucks less!” Quote from the lead developer. Checking email requires a web-based front-end or a separate mail client. These require graphical environments, with few exceptions. Neomutt is one such exception. With Neomutt, you can check your emails on the command line in a separate application. You may be limited when it comes to web-based emails, but there are workarounds also for that inconvenience.

The basic ideas

To understand, you need to understand the basic concepts. The main one is the views you have for each job; listing the mails and reading each mail.


Neomutt starts with the Index Screen. This shows all emails listed the way you want. Whether you see read emails or not, you can set yourself. The default behaviour is to show all emails even when they are marked deleted; you later move them to trash. You choose an email with arrows, vim keys, or what you specify yourself in the index screen. To open them, hit enter and they will appear in the Pager screen.

Pager (Showing the Emails)

In the pager, your emails will show. In the basic form, you will only see text-based mails. To see HTML, you need to designate your web browser and have Neomutt call it up. Neomutt will make a temporary file that contains the corresponding web page that is the email.


The sidebar keeps all the mailboxes you have available, there can be many! You can choose to have this, not have it or toggle it with a key-binding. Most users will have a key-binding, like ‘B’, for example.


You navigate your inbox with the arrow keys and scroll down emails with the space bar. To delete the email, you use ‘D’. All these things are common, and you can set them yourself with the configuration file. The interesting part is that you need to know the index and the pager. When you configure neomutt, the settings will be according to which view you use. Most of these will be for both views.

Binding keys

In neomutt, you will work with the keyboard exclusively. It is a terminal-based application, after all. For this reason, you will want to bind different keys to the functions you use the most. Earlier, you could read the standard bindings; if you want to change something, you need to bind them your self. To bind capital ‘B’ to toggle the sidebar, for example, use the below code.

bind index,pager B sidebar-toggle-visible

The list will end up fairly long so sourcing a separate file for the key-bindings is a good idea. The format is pretty simple; a capital letter means exactly that. To show Ctrl-x, you put \c-x

Connecting an account

The first thing you need to do is to connect an account. You can do this with one command at a time; you will need up to twenty commands to get to your mailbox. Not what you want to do daily. It can be helpful when you try to set up a new account. In ordinary use, you want to have the account open when you start neomutt. This requires a configuration file. In the file, you will need to set all the values for the account.

# Imap settings

set imap_user = "[email protected]"

set imap_pass = ""


# Smtp settings

set smtp_url = "smtps://"

set smtp_pass = ""


# Remote folders

set folder = "imaps://"

set spoolfile = "+INBOX"

set postponed = "+/Drafts"

set record = "+/Sent Mail"

set trash = "+/Trash"


account-hook $folder "set imap_pass=""

The parameters are pretty simple to understand; you may have different passwords for IMAP and SMTP though it is rare. What can be confusing is the folder value. This configuration is for IMAP; the folder you are setting is on the remote server. You can use a local store for your emails, but that is another setup. The password is empty in this case. When you run, neomutt will ask for your password every time you start. If you set the password, neomutt will collect it from this config file. It is good practice to encrypt the file where the password is!

Web contents

When an email is written in HTML, you cannot read it with Neomutt, by default. You can access the mail in your default browser, though. On most systems, when you open an email, it will show that you cannot read HTML in the email client. When you press v, as it says in the pager, your default browser will open it. This is determined by the ~/.mailcap file. You find ‘text/html’ a semi-colon and the browser you will use in the file. On Debian based systems, it calls ‘/usr/bin/sensible-browser’. To set this value, you need to change it in ‘/etc/alternatives/x-www-browser’ and ‘/etc/alternatives/gnome-www-browser’. This is for the whole system.

$ sudo update-alternatives –config x-www-browser

$ sudo update-alternatives –config gnome-www-browser

$ xdg-settings set default-web-browser brave-browser.desktop

Note that the last one is for your use only, in case you do not have root to your system. You can also set any other web browser only for mail. You do this by setting mailcap directly to a browser.


The neomutt package is very versatile, but the configuration is confusing and needs more well-explained tutorials and examples than you have seen here. With your mailbox overflowing with HTML-mails you may think twice about switching to a text-based mail pager. Consider, though, that you can use it as a filter. Most commercial emails are in HTML only, are your other emails in plain text?

About the author

Mats Tage Axelsson

I am a freelance writer for Linux magazines. I enjoy finding out what is possible under Linux and how we can all chip in to improve it. I also cover renewable energy and the new way the grid operates. You can find more of my writing on my blog.