How to Set Up Mutt with Gmail on Linux Using OfflineIMAP

Installing Mutt

Install the Mutt package from the system package manager and create a configuration directory.

$ sudo dnf install mutt
$ mkdir ~/.mutt

On macOS use Homebrew or MacPorts; on Windows use Chocolatey.

Installing OfflineIMAP and its Python dependencies

OfflineIMAP synchronises a remote IMAP mailbox to a local Maildir. It requires the imaplib2 library, which must be built from source. $ python3 -m pip install --user rfc6555 Clone and install imaplib2:

$ git clone [email protected]:jazzband/imaplib2.git
$ pushd imaplib2
$ python3 -m pip install --upgrade --user .
$ popd

Clone and install OfflineIMAP (the offlineimap3 repository):

$ git clone [email protected]:OfflineIMAP/offlineimap3.git
$ pushd offlineimap3
$ python3 -m pip install --upgrade --user .
$ popd

If you are using Cygwin on Windows, also install Portlocker.

Configuring OfflineIMAP

Copy the example configuration supplied in the repository to ~/.offlineimaprc:

$ mv offlineimap3/offlineimap.conf ~/.offlineimaprc

Edit the file and replace the two placeholders with your Gmail credentials: %your-gmail-username% – the part of your Gmail address before

@gmail.com

%your-gmail-API-password%

– the application password generated after enabling two‑step verification.

A minimal configuration (only the essential sections) looks like:

[general]
ui = ttyui
accounts = %your-gmail-username%

[Account%your-gmail-username%]
localrepository = %your-gmail-username%-Local
remoterepository = %your-gmail-username%-Remote
status_backend = sqlite
postsynchook = notmuch new

[Repository%your-gmail-username%-Local]
type = Maildir
localfolders = ~/.mail/%your-gmail-username%-gmail.com

[Repository%your-gmail-username%-Remote]
maxconnections = 1
type = Gmail
remoteuser = %your-gmail-username%@gmail.com
remotepasseval = '%your-gmail-API-password%'
sslcacertfile = /etc/ssl/certs/ca-bundle.crt
realdelete = no
nametrans = lambda folder: {
    'drafts': '[Gmail]/Drafts',
    'sent': '[Gmail]/Sent Mail',
    'flagged': '[Gmail]/Starred',
    'trash': '[Gmail]/Trash',
    'archive': '[Gmail]/All Mail'
}.get(folder, folder)
folderfilter = lambda folder: folder not in ['[Gmail]/Trash','[Gmail]/Important','[Gmail]/Spam']

Enabling Gmail IMAP and generating an app password

In Gmail web UI go to Settings → “See all settings” → “POP/IMAP” and enable IMAP. Then open the Google Account security page, enable two‑step verification, and create an “App password” for Mutt. Insert that password into the %your-gmail-API-password% placeholder.

Configuring Mutt

Create or edit ~/.mutt/muttrc with the following essential settings (replace placeholders with your real name and email address):

set ssl_starttls=yes
set ssl_force_tls=yes
set folder=imaps://imap.gmail.com/
set spoolfile=imaps://imap.gmail.com/INBOX
set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
set smtp_url="smtp://smtp.gmail.com:25"
set imap_keepalive=900
set mbox_type=Maildir
set folder=~/.mail
set alias_file=~/.mutt/alias
set header_cache="~/.mutt/cache/headers"
set message_cachedir="~/.mutt/cache/bodies"
set certificate_file=~/.mutt/certificates
set tmpdir=~/.mutt/temp
set signature=~/.mutt/sig
set sig_on_top=yes
set sidebar_visible=yes
set sidebar_width=16
mailboxes +INBOX +sent +drafts
# Example macros (the angle brackets are escaped as HTML entities)
macro index gi "<change-folder>=example.com/INBOX<enter>" "Go to inbox"
macro index gt "<change-folder>=example.com/sent<enter>" "View sent"

Running OfflineIMAP and starting Mutt

Synchronise the remote mailbox to the local Maildir: $ offlineimap After the initial sync finishes, start Mutt: $ mutt Mutt will ask for permission to access the mail directory and then display the inbox view.

Further customisation

The .muttrc file can be extended with Emacs‑style composition, LDAP address lookup, GnuPG encryption, HTML rendering, and additional macros. The configuration shown provides a functional baseline for a terminal‑based Gmail workflow.