OfflineImap

Syncing IMAP accounts since 2002

OfflineImap synchronizes emails between two repositories, so that you can read the same mailbox from multiple computers. It supports IMAP as REMOTE repository and Maildir/IMAP as LOCAL repository. See below for a full list of features.

Overview

Configuring OfflineImap in basic mode is quite easy, however it provides an amazing amount of flexibility for those with special needs. You can specify the number of connections to your IMAP server, use arbitrary python functions (including regular expressions) to limit the number of folders being synchronized. You can transpose folder names between repositories using any python function, to mangle and modify folder names on the LOCAL repository. There are six different ways to hand the IMAP password to OfflineImap from console input, specifying in the configuration file, .netrc support, specifying in a separate file, to using arbitrary python functions that somehow return the password. Finally, you can use IMAPs IDLE infrastructure to always keep a connection to your IMAP server open and immediately be notified (and synchronized) when a new mail arrives (aka Push mail).

Most configuration is done via the configuration file. However, any setting can also be overriden by command line options handed to OfflineIMAP.

OfflineImap is well suited to be frequently invoked by cron jobs, or can run in daemon mode to periodically check your email (however, it will exit in some error situations).

OfflineIMAP was originally written by John Goerzen, who retired from maintaining it at then end of 2010. It is now maintained by Nicolas Sebrecht. We are grateful for the great job John did and for having shared his project with us.

It is a Free Software project licensed under the GNU General Public License (v2+). You can download it for free, and you can modify it. In fact, you are encouraged to contribute changes back to us.

How it works

OfflineIMAP traditionally operates by maintaining a hierarchy of mail folders in Maildir format locally. Your own mail reader will read mail from this tree, and need never know that the mail comes from IMAP. OfflineIMAP will detect changes to the mail folders on your IMAP server and your own computer and bi-directionally synchronize them, copying, marking, and deleting messages as necessary.

OfflineIMAP can also synchronize two IMAP servers with each other, with no need to have a Maildir layer in-between. Many people use this if they use a mail reader on their local machine that does not support Maildirs. People may install an IMAP server on their local machine, and point both OfflineIMAP and their mail reader of choice at it. This is often preferable to the mail reader's own IMAP support since OfflineIMAP supports many features (offline reading, for one) that most IMAP-aware readers don't. However, this feature is not as time-tested as traditional syncing, so my advice is to stick with normal methods of operation for the time being.

For a more detailed explaination of the internal algorithm, please refer to this page: Algorithm detail

System requirements

OfflineIMAP works on pretty much any POSIX operating system, such as Linux, BSD operating systems, MacOS X, Solaris. With some fiddling, it reportedly ran under Windows as well (TODO: Is there Win documentation?).

Required: Python >= 2.6, and optionally (but recommended) python-sqlite.

Source code

The source code is hosted in a github git repository. Retrieve the git repository by issueing git clone git://github.com/OfflineIMAP/offlineimap.git. The release tarballs are automatically created by corresponding git tags, ie to retrieve release 6.4.0 you would issue git checkout v6.4.0 in your git checkout. If you are simply interested in the latest stable version, go here, get and install it.

Quick Start

If you have already installed OfflineIMAP system-wide, or your system administrator has done that for you, your task for setting up OfflineIMAP for the first time is quite simple. You just need to set up your configuration file, make your folder directory, and run it!

You can quickly set up your configuration file. The distribution includes a file offlineimap.conf.minimal (Debian users may find this at /usr/share/doc/offlineimap/examples/offlineimap.conf.minimal) that is a basic example of setting of OfflineIMAP. You can simply copy this file into your home directory and name it .offlineimaprc (note the leading period). A command such as cp offlineimap.conf.minimal ~/.offlineimaprc will do it. Or, if you prefer, you can just copy this text to ~/.offlineimaprc:

[general]
accounts = Test

[Account Test]
localrepository = Local
remoterepository = Remote

[Repository Local]
type = Maildir
localfolders = ~/Test

[Repository Remote]
type = IMAP
remotehost = examplehost
remoteuser = jgoerzen

Now, edit the ~/.offlineimaprc file with your favorite editor. All you have to do is specify a directory for your folders to be in (on the localfolders line), the host name of your IMAP server (on the remotehost line), and your login name on the remote (on the remoteuser line). That's it!

To run OfflineIMAP, you just have to say offlineimap ― it will fire up, ask you for a login password if necessary, synchronize your folders, and exit. That's it. See?

You could just throw away the rest of this finely-crafted, perfectly-honed manual! However, the default settings are not tuned for maximum performance so make sure you read the documentation to make sure you get the most out of OfflineIMAP.

Documentation

The user documentation is contained in the source git repository in the docs directory and can be generated by issueing make doc and make dev-doc.

The full documentation is also provided online for easy browsing. Do peruse, it might help you solve your problems and tweak OfflineIMAP. The manual contains explanations, hints, and typical use cases.

The full developer documentation can also be viewed online. It contains the code documentation of all relevant functions in the OfflineImap source code base and should help in case you plan to modify or improve OfflineImap.

Installation

  1. Grab it via your distribution's package manager
  2. Grab the latest release and install it system-wide.
  3. Grab the master.tar.gz latest release and run it locally by unpacking, cd'ing into the offlineimap directory and issueing ./offlineimap.py (you need to configure things beforehand).
The full installation instructions are also part of the source code repository and can be viewed online.

Important links

All important links at a glance...
Source code
  • Current github home
    git clone git://github.com/OfflineIMAP/offlineimap.git
  • release tarballs
  • Via your distributions package manager for

    Debian, Ubuntu, Fedora, Gentoo, Arch, ...

Bugs & Discussion
Related projects

Examples

We have collected some examples for typical use case configurations and some how-tos on the examples page.