# mutt-wizard: configure neomutt, isync and msmtp from one command

> mutt-wizard generates the dotfiles for a terminal email client, stores your password behind GPG, and keeps mail offline. It is a good fit for people who already want neomutt, and a poor fit for anyone who does not.

**LukeSmithxyz/mutt-wizard** — A system for automatically configuring mutt and isync with a simple interface and safe passwords

- Repository: https://github.com/LukeSmithxyz/mutt-wizard
- Stars: 2,641 · Forks: 383
- Language: Shell
- License: GPL-3.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/lukesmithxyz-mutt-wizard

## What mutt-wizard actually removes from the neomutt setup

Configuring neomutt by hand means writing three separate configuration files that have to agree with each other. neomutt needs to know where mail lives and how to send it. isync needs the IMAP host, port and authentication details. msmtp needs the SMTP host, port and credentials. Get one port wrong and mail arrives but never leaves, or leaves but never arrives.

mutt-wizard exists to write those files for you. The README states that it determines your email server's IMAP and SMTP servers and ports, then creates dotfiles for neomutt, isync and msmtp appropriate for your address. It also encrypts and stores your password locally, accessible only by your GPG key, and handles as many as nine separate accounts, creating bindings to switch between accounts and between mailboxes.

The intended user is someone who has already decided to read mail in a terminal. mutt-wizard does not make that decision for you and does not soften it. It removes the configuration work, not the terminal. If you want a mail client with a window, this project has nothing to offer you.

## How the mw command, pass and mailsync fit together

The moving parts are visible in the repository layout: bin/ holds the mw and mailsync scripts, lib/ holds openfile, share/ holds the muttrc template and mailcap, and completion/ holds a zsh completion file. The Makefile copies those into $(PREFIX)/bin, $(PREFIX)/lib/mutt-wizard and $(PREFIX)/share/mutt-wizard, and rewrites the hardcoded /usr/local prefix with sed as it installs.

The data flow is three-stage. mw -a writes the account configuration and stores the password through pass under a key named mw-your@email.com. isync then downloads mail into ~/.local/share/mail/, which the README names as the mail directory it tells notmuch to index. neomutt reads the local store, and msmtp sends outgoing mail. mailsync is the script that drives the download step; the README says it can be scheduled as often as you like, gives notifications of new mail, and indexes new mail with notmuch silently.

Two details are worth knowing before you rely on this. The password never lands in a plaintext config file, since it is retrieved from pass at runtime. And the mail store is local, which is what makes offline reading and backups possible, but also means the first sync of a large mailbox is a real download.

## Installing mutt-wizard and adding your first account

The README lists neomutt, curl, isync, msmtp, pass, ca-certificates and gettext as dependencies. curl and pass are marked as required at install, isync is required if you store IMAP mail locally, and msmtp sends the email. Install those through your distribution first, then clone and run the Makefile.

```bash
git clone https://github.com/LukeSmithxyz/mutt-wizard
cd mutt-wizard
sudo make install
```

The Makefile installs mw into /usr/local/bin by default and the shared files into /usr/local/share/mutt-wizard. Arch users have a second route: the README points to the AUR packages mutt-wizard for the current release and mutt-wizard-git for the master branch.

Adding an account is one command. You will be prompted for the password unless you pass it with -x.

```bash
mw -a you@email.com
```

After that, mw -l lists existing accounts and mailsync fetches mail. The README gives mw -t 30 as the way to toggle automatic mailsync to every 30 minutes, and mw -T to toggle it without specifying minutes, with a default of 10. To revise a stored password, the documented command is pass edit mw-your@email.com.

If your provider is not recognised, the README says mutt-wizard prompts you for the IMAP and SMTP details and puts them in the right places. You can also supply them up front with -i, -I, -s and -S, where -I defaults to 993 and -S to 465. The -f flag assumes mailbox names and forces configuration without connecting online at all, which is the documented escape hatch when a live connection check fails.

## Where mutt-wizard breaks or is the wrong tool

The README carries its own warning: there is a chance of errors if you use a slow-release distro like Ubuntu, Debian or Mint. The suggested fixes are to install the most recent neomutt manually or to remove the offending lines in the config at /usr/share/mutt-wizard/mutt-wizard.muttrc. That is a real maintenance burden. It means the generated configuration can assume neomutt features that your distribution's package does not have, and the resolution is editing a file the tool installed.

Provider coverage is the second limit. The wizard knows a set of IMAP and SMTP servers by default. When it does not know yours, it falls back to prompting, and the -f flag exists specifically to skip the online check. If your provider uses something other than a plain IMAP/SMTP pair, such as an OAuth-only login, nothing in the documented flags addresses it. The README does not document rollback either, so undoing a bad account means mw -d to choose an account to delete or mw -D your@email.com to delete settings without confirmation.

Finally, this is the wrong tool if you do not want to install pass and manage a GPG key. Password storage is not optional here; it is part of the design, and pam-gnupg is only an optional convenience for logging into that key at login.

## mutt-wizard against configuring neomutt by hand

The honest alternative is not another wizard. It is writing the neomutt, isync and msmtp configuration yourself, which is what the people who dislike this project usually do.

The difference in approach is where the knowledge lives. Hand-written configs put the server names, ports and mailbox mappings in files you own and can read line by line; nothing regenerates them and nothing overwrites them. mutt-wizard puts that knowledge in the script and its share/ templates, and generates your files from them. You gain speed on the first account and on accounts two through nine, since the README states it handles as many as nine automatically and auto-creates bindings between them. You give up the ability to reason about the whole configuration at a glance, because part of it now lives in /usr/local/share/mutt-wizard.

That trade is reasonable for someone with several accounts and no interest in isync syntax. It is a bad trade for someone with one account who enjoys the configuration, because the generated files are exactly the thing they would have written anyway, minus the control.

## Maintenance, licence and what upgrading costs you

The repository is not archived, and the last push was on 2026-07-26. The most recent tagged release in the repository is v3.3.1 from 2022-04-30, described as a Debian compliance release, with v3.2.1 and v3.1.1 before it. The gap between the last tag and the last push is the practical story: the master branch moves, but the release cadence is slow, and Arch users choosing between mutt-wizard and mutt-wizard-git are effectively choosing between those two positions.

Upgrading is cheap in the normal case. The Makefile has an uninstall target that removes the binaries, the man pages and the share directories, and reinstalling is the same sudo make install. The cost is not the upgrade itself but the local edits: if you followed the README and removed offending lines from mutt-wizard.muttrc, a reinstall rewrites that file from share/mutt-wizard.muttrc with sed, so your edits go away.

The project is GPL-3.0. That matters mainly if you redistribute a modified copy or ship it inside a larger product, since the licence carries obligations in that case. Running it on your own machine to configure your own mail is not the scenario the copyleft terms are aimed at. This is a description of the licence identifier, not legal advice; read the LICENSE file in the repository if redistribution is on your roadmap.

## Conclusion

Adopt mutt-wizard if you already want neomutt and are willing to install neomutt, isync, msmtp, pass and curl before running sudo make install. Do not adopt it if you want a graphical client, a web interface or a mail system that you never configure by hand. Before trusting it with a work account, run mw -a on a throwaway address, confirm that mw -l lists it, that mailsync fetches mail, and that pass edit mw-your@email.com opens the right entry. If a provider rejects the connection, the README's own fallback is the -f flag plus explicit -i, -I, -s and -S values, so verify those before blaming the tool.

## FAQ

### What are the differences between NeoMutt and Mutt?

The README does not compare the two. It describes mutt-wizard as building an autoconfigured email client on the terminal with neomutt, and its configuration files are written for neomutt, which the dependency list names as the email client. If you are choosing between the two clients, that choice happens before mutt-wizard enters the picture.

### What is mutt in Linux?

The README does not define mutt itself. It treats neomutt as the email client and mutt-wizard as the layer that configures it, generating dotfiles for neomutt, isync and msmtp so that mail can be read and written in a terminal, including offline.

### What is the Mutt e-mail client?

The README points to neomutt as the email client in this setup and lists it as a dependency. mutt-wizard's job is to write the configuration that client needs, along with the isync and msmtp files for downloading and sending mail.

### How do I configure mutt?

The README's answer is to install mutt-wizard and run mw -a you@email.com, which determines your server's IMAP and SMTP settings and writes the neomutt, isync and msmtp dotfiles. If the server is not recognised, it prompts for the details, and -i, -I, -s and -S let you supply the IMAP and SMTP addresses and ports yourself.

## Sources

- [Issues](https://github.com/LukeSmithxyz/mutt-wizard/issues)
- [License: GPL-3.0](https://github.com/LukeSmithxyz/mutt-wizard/blob/master/LICENSE)
- [LukeSmithxyz/mutt-wizard on GitHub](https://github.com/LukeSmithxyz/mutt-wizard)
- [README](https://github.com/LukeSmithxyz/mutt-wizard/blob/master/README.md)
- [Releases](https://github.com/LukeSmithxyz/mutt-wizard/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lukesmithxyz-mutt-wizard