Newbie Tutorial

Things every Newbie Should Know

If you’re new to NeoMutt, here’s a list of things you need to know.



The NeoMutt developers are scattered all over the globe. To keep in touch they use GitHub, IRC and mailing lists.


Channel: #neomutt on

This is a good way to meet the developers if you want to say hello. Everyone’s welcome. There are usually about 190 people / lurkers in the channel.

The channel is pretty informal and conversation ranges from deep technical discussions to light-hearted nonsense (late at night).

If you don’t have a IRC client, you can use Libera’s web client.

Mailing lists

NeoMutt has two moderated mailing lists: Users, Devel.

NeoMutt Users (~200 people)

This list is ideal for new users of NeoMutt and people wanting to learn more.

All non-technical NeoMutt discussions are welcome here.

  • What’s your favourite feature?
  • Do you have a killer config file?
  • Have you found a bug?
  • Do you want some help?

When asking for help, remember that we’re volunteers. (and please check Google first :-)

NeoMutt Developers (~100 people)

This is a technical list, used for discussing the code, build and documentation of NeoMutt.

Users of rolling releases, such as Arch, Gentoo and Homebrew (OSX) are advised to join, to get early warning of new bugs.

Discussions here are likely to be about:

Bugs, Features, Code, Distros, Enhancements, Git

Mailing List Guidelines


  • Send emails in plain text, not HTML
  • Use an informative subject line
  • Keep attachments small, or better still: link to the files
  • Remember that we’re volunteers and we may take a while to reply


If you’re a GitHub user, there are lots of ways to keep informed about NeoMutt development.

First, though, please star our project to show your appreciation :-)

The project consists of about 20 Git repositories. They store the code that makes up NeoMutt, the documentation, build scripts and experiments (read more about them).

GitHub allows you to watch:

  • Repos – Choose a repository and click the Watch button
  • Issues – Open an issue and click Subscribe in the right-hand panel
  • Pull-Requests – Open a PR and click Subscribe in the right-hand panel
  • People – Go to a person’s home page and click Follow on the left

By watching things in GitHub, you will receive emails when events occur. See your notifications and emails settings for more information.

Usage tips

  • We use GitHub’s “assignee” feature to communicate who’s working on what. That way, we can easily identify who’s working on what.
  • Please read and understand GitHub’s documentation for searching through issues and pull requests.


We use GitHub labels to categorize pull requests and issues. Here’s a list of them with their meanings. Please make use of them and ask if something is unclear.


Some of our Branches have a special meaning.


This section is for people who have been invited to join the NeoMutt project. Invites will be given to people who contribute: code, docs, translations and to the people who maintain NeoMutt packages for distros (it’s a very inclusive club :-)

Thank you for your contribution and Welcome to NeoMutt.

Accepting an invitation does two things. It shows your support for the project and it allows you to commit work directly to the project. Members can commit to most branches of most repos. Everything is backed up, but please be careful :-)

When you join, please consider making your membership public. Being a public member will add a NeoMutt icon to your home page and it will tag any comments you make in the issues.


All NeoMutt members are welcome to join our Teams. This allows you to @mention people with similar interests.

  • Arch Users
  • Debian Users
  • Gentoo Users
  • Homebrew Users
  • Notmuch Users
  • Downstream Packagers

What you can do in NeoMutt


Do you want to fix Mutt?
Do you want to add new features to Mutt?

To get familiar with the NeoMutt code, you can start with some Easy Coding Tasks

Whatever your level of skill, NeoMutt has got a task for you. There are lots of simple jobs and lots of hard jobs to get you thinking.

Alternatively, you could add a new feature to Mutt. There are many great Mutt patches that have been neglected. They need to be brought up-to-date and merged into Mutt.

Required tools

Usually, the .travis.yml files are a good starting point here.

Coding style

Over its twenty year life, Mutt has gathered 84,000 lines of code and a lot of cruft (messy code and bad habits). It’s time to sort out the mess and make Mutt robust. We have written up the consensus among the NeoMutt Developers in the coding style Section. You can make of course suggestions to that – but please follow the consensus. Otherwise it makes the work very hard.

Of course, especially refactorings/cleanups of the source code are welcome. If you are interested, please talk to us.

Warning of string comparisons

A word of warning about string comparisons: Since Mutt may run in a huge variety of locales, case-insensitive string comparisons and case conversions may be dangerous. For instance, in ISO-8859-9, tolower(‘I’) is DIFFERENT from ‘i’ – it’s indeed the Turkish dotless lowercase i.

For this reason, always use the ASCII_* functions defined in ascii.h and implemented in ascii.c when comparing or handling strings which are defined as US-ASCII. This concerns lots of text-based protocols, message header tags, character set names, domain names, e-mail addresses, etc.


The NeoMutt Guide reads like an encyclopaedia. Everything you want to know is in there somewhere, but generally you have to know what you’re looking for.

NeoMutt needs a simple introduction with pictures. The guide should explain how to perform simple tasks (just the basics to get a user started). The simple guide can list some more advanced features of NeoMutt, but leave a full explanation to the main manual.

See also: Docs Rebuild

The NeoMutt program has been translated into 30 languages, but some of the translations are out-of-date.

Web design

This website was created by a programmer – it shows. If you think you could do a better job, prove it.

Please don’t edit the *.html and *.md files in the following folders, as they are semi-automatically generated:

Of course, you can always send pull requests to update those folders.

The site contains information from quite a lot of sources. Most of it has been pulled together by hand. These processes need to be automated to reduce effort.


The NeoMutt project has a GitHub organisation and a website

These are useful and practical, but in order to reach a wider audience we have a Twitter and probably need a Facebook presence.


NeoMutt already contains lots of features that Mutt doesn’t have. These features were often only available as patches which meant that they didn’t get much testing.

Do you know to to use automatic testing tools? What tools exist to test text-only programs like Mutt? How easy is it to set up tests? What are these tools capable of?

If you find a bug in NeoMutt, please report it: NeoMutt issue.


Even if you don’t have any technical skills, you can probably help here. As a mail client, Mutt is missing many features common to modern programs. Help compile a list of features that Mutt is missing; help guide development.


NeoMutt is currently only available as source code / patches. NeoMutt is a small project and creating and maintaining binary packages takes time.

We need someone to create binary packages of NeoMutt. A good way to do this would be to set up a Debian PPA or Fedora COPR.

Automatic packaging, and release, would mean more users, more testing and better quality.


Mutt has very few developers. This won’t change until the Mutt community becomes more welcoming to new developers.

Do you know Mutt well?
Do you want to encourage others to help?

Richard Russon has compiled a list of simple coding tasks. Each task will improve the state of the Mutt code and help to get new developers familiar with Mutt.

The job of the mentor will be to:

  • Answer the new coder’s questions about Mutt
  • Check the work
  • Help get the code accepted into Mutt

Search by Algolia