Most email readers like Gnus and mutt provide an interface for fetching emails through the IMAP protocol. You might find this feature the most convenient way to get started using a stack-based solution for your email needs, but there’s a catch: it’s slow. Also, it means that your messages are only available while you have network connectivity.

What OfflineIMAP provides is a syncing process between remote IMAP repositories, like your mail server, and a local directory that stores the messages in the maildir format. This allows you to access your email while offline. It also ensures better performance from your mail client, (which can mean a lot in cases such as Gnus, where your mail client is also your text editor).

Getting Started

Fedora Linux provides OfflineIMAP in the official repositories. You can install it and keep it up-to-date using the DNF package manager. For instance,

# dnf install offlineimap

Once DNF finishes the installation, you can run OfflineIMAP using the offlineimap application. When the application runs, it looks for a configuration file at ~/.offlineimaprc. While you can give it a path to a different file, using the -c flag, bear in mind that it won’t run properly until you configure the accounts you want it to check.

Basic Configuration

OfflineIMAP uses the Unix config standard for its .offlineimaprc configuration file. The file divides into a series of unit, each with its own set of parameters to define how you want OfflineIMAP to use each.

There are three basic unit types:

  • General: Defines system configurations, the accounts to check and any Python files that you want to load:

    accounts = Personal, Business
    pythonfile = ~/repos/email/
  • Account: Defines an account with the repositories it uses. The unit title must contain a value given to the accounts parameter above:

    [Account Personal]
    localrepository = Personal-Local
    remoterepository = Personal-Remote
  • Repository: Defines the local and remote repositories assigned to the account and how it should handle each. The second argument in the unit title derives from either the localrepository or remoterepostiory parameters in the given Account unit:

    [Repository PersonalLocal]
    type = Maildir
    localfolders = /path/to/maildir
    [Repository PersonalRemote]
    type = Gmail
    remotehost =
    remoteuser =
    remotepasseval = my_secret_passwd
    sslcacertfile = /etc/ssl/certs/ca-bundle.crt

When you are satisfied with the configuration, save the file to the ~/.offlineimaprc path. Then run OfflineIMAP. In the event that you have several accounts that you want to sync for the first time, you may want to use the --dry-run flag, to ensure that everything is working before you begin the sync.

$ offlineimap --dry-run
OfflineIMAP 6.7.0
  Licensed under the GNU GPL v2 or any later version (with an OpenSSL exception)
Account sync Personal:
 *** Processing account Personal
 Establishing connection to
Folder INBOX [acc:Personal]:
 Syncing INBOX: Gmail -> Maildir

Bear in mind, the first time you sync any account, (especially an existing account that you have had for some time), you expect a fairly lengthy run-time as OfflineIMAP needs to download all of your emails in order to sync the local maildir with the remote repository.


In the above example, the password to your email account is given in plain text. Remember to apply the appropriate permissions to the .offlineimaprc configuration file in order to ensure that only authorized users can read it.

Later sections cover different methods of password encryption with OfflineIMAP.

< Prev Next >