From ArchWiki
Revision as of 12:09, 28 June 2011 by Orcus (talk | contribs) (accounts should be comma delimited)
Jump to: navigation, search

OfflineIMAP is an utility to sync mail from IMAP servers. It does not work with the POP3 protocol or mbox, and is usually paired with a MUA such as Mutt.

As of 06/26/2010, the original author of offlineimap ceased development. A new maintainer has since stepped forward and as of 12/16/2010 developed seemed to be active.


Install the Template:Package Official package with pacman:

# pacman -S offlineimap


The example configuration that is distributed with offlineimap contains every setting and is thorougly documented.

Copy it to Template:Filename and edit it:

$ cp /usr/share/offlineimap/offlineimap.conf ~/.offlineimaprc
$ vi ~/.offlineimaprc

Writing a comment after an option/value on the same line is invalid syntax, hence take care that comments are placed on their own separate line.


Following is a commented version of Template:Filename. The setup only contains settings that are absolutely necessary. Template:File


Before running offlineimap, create any parent directories that were allocated to local repositories:

$ mkdir ~/Maildir

Now, run the program:

$ offlineimap

Mail accounts will now be synced. If anything goes wrong, take a closer look at the error messages. OfflineIMAP is usually very verbose about problems; partly because the developers didn't bother with taking away tracebacks from the final product.


Various settings and improvements

Running offlineimap in the background

Most other mail transfer agents assume that the user will be using the tool as a daemon by making the program sync periodically by default. In offlineimap, there are a few settings that control backgrounded tasks.

Confusingly, they are spread thin all-over the configuration file: Template:File

cron job

1. Configure background jobs as shown in #Running offlineimap in the background.

2. Use a log-friendly user interface: Template:File

3. Write a wrapper script for daemonizing programs, or use the one shown below: Template:File

4. Finally, add a crontab entry:

$ crontab -e

The line should specify the interpreter for correct Template:Codeline results:

*/5 * * * * exec /usr/local/bin/start_daemon -n19 -c2 -p7 python2 /usr/bin/offlineimap 

If you are using offlineimap-git from AUR, you'll want to change python2 to python

The wrapper script is needed because offlineimap has the tendency to sporadically crash, even more so when facing connection problems.

Automatic mutt mailbox generation

Mutt cannot be simply pointed to an IMAP or maildir directory and be expected to guess which subdirectories happen to be the mailboxes, yet offlineimap can generate a muttrc fragment containing the mailboxes that it syncs. Template:File

Then add Template:Codeline to Template:Filename.

Gmail configuration

This remote repository is configured specifically for Gmail support, substituting folder names in uppercase for lowercase, among other small additions. Keep in mind that this configuration does not sync the All Mail folder, since it is usually unnecessary and skipping it prevents bandwidth costs:


Note: if you have Gmail set to another language, the folder names may appear translated too, e.g. "verzonden_berichten" instead of "sent_mail".

Not having to enter the password all the time gives an example of how to use gnome-keyring to store the password.

Anyone know whether this is possible with KDE wallets?


Overriding UI and autorefresh settings

For the sake of troubleshooting, it is sometimes convenient to launch offlineimap with a more verbose UI, no background syncs and perhaps even a debug level:

$ offlineimap [ -o ] [ -d <debug_type> ] [ -u <ui> ]
Disable autorefresh, keepalive, etc.
-d <debug_type>
Where <debug_type> is one of Template:Codeline, Template:Codeline or Template:Codeline. Debugging imap and maildir are, by far, the most useful.
-u <ui>
Where <ui> is one of Template:Codeline, Template:Codeline, Template:Codeline, Template:Codeline or Template:Codeline. TTY.TTYUI is sufficient for debugging purposes.

Curses interface (Curses.Blinkenlights) locks terminal

Because of a bug in Python's ncurses package ( the Curses interface of OfflineIMAP breaks the terminal on exit. While it appears to irreparably lock the terminal, in reality it only prevents commands from being displayed. The bug has been fixed in Python's SVN for all versions 2.6 up to 3.2 but the current package in the repositories (Python 2.6.5) is still buggy.

In order to solve the issue:

$ offlineimap; reset
  • or as quick workaround you can just use the following command to skip the reset() function in which causes the problem
# sed -i '125i\ \ \ \ \ \ \ \ return' /usr/lib/python2.6/site-packages/offlineimap/ui/

netrc authentication

There are some bugs in the current Template:Package Official which makes it impossible to read the authentication data from Template:Filename if there are multiple Accounts per remote machine. ( see Mail Archive ) But they are fixed in the GIT package Template:Package AUR (note that is AUR package is flagged as out of date; see the current GitHub external link below). Using the package you can collect all passwords in Template:Filename. And don't forget to set it's access rights:

chmod 600 ~/.netrc

An example netrc file would be Template:File

socket.ssl deprecation warnings

Depending on the currently installed python version, running offlineimap throws this warning:

DeprecationWarning: socket.ssl() is deprecated.  Use ssl.wrap_socket() instead.

This can be particularly annoying when offlineimap's output is being logged or mailed through cron.

To fix the problem, apply this upstream patch or install Template:Package AUR:

--- offlineimap/	2009-08-12 01:24:23.000000000 -0430
+++ offlineimap/		2010-06-07 11:17:37.849038683 -0430
@@ -23,9 +23,11 @@
 # Import the symbols we need that aren't exported by default
 from imaplib import IMAP4_PORT, IMAP4_SSL_PORT, InternalDate, Mon2num
-# ssl is new in python 2.6
-if (sys.version_info[0] == 2 and sys.version_info[1] >= 6) or sys.version_info[0] >= 3:
     import ssl
+    ssl_wrap = ssl.wrap_socket
+except ImportError:
+    ssl_wrap = socket.ssl
 class IMAP4_Tunnel(IMAP4):
     """IMAP4 client class over a tunnel
@@ -169,7 +171,7 @@
         if last_error != 0:
             # FIXME
             raise socket.error(last_error)
-        self.sslobj = socket.ssl(self.sock, self.keyfile, self.certfile)
+        self.sslobj = ssl_wrap(self.sock, self.keyfile, self.certfile)
         self.sslobj = sslwrapper(self.sslobj)
 mustquote = re.compile(r"[^\w!#$%&'+,.:;<=>?^`|~-]")

The diff is relative to the root buildir and it can be applied by using ABS.

External links