1 OFFLINEIMAP(1) OfflineIMAP manual OFFLINEIMAP(1)
6 OfflineIMAP - Powerful IMAP/Maildir synchronization and
10 offlineimap [ -1 ] [ -a accountlist ] [ -c configfile ]
11 [ -d ] [ -o ] [ -u interface ]
13 offlineimap -h | --help
16 OfflineIMAP is a tool to simplify your e-mail reading.
17 With OfflineIMAP, you can read the same mailbox from mul-
18 tiple computers. You get a current copy of your messages
19 on each computer, and changes you make one place will be
20 visible on all other systems. For instance, you can
21 delete a message on your home computer, and it will appear
22 deleted on your work computer as well. OfflineIMAP is
23 also useful if you want to use a mail reader that does not
24 have IMAP support, has poor IMAP support, or does not pro-
25 vide disconnected operation.
27 OfflineIMAP is FAST; it synchronizes my two accounts with
28 over 50 folders in 3 seconds. Other similar tools might
29 take over a minute, and achieve a less-reliable result.
30 Some mail readers can take over 10 minutes to do the same
31 thing, and some don't even support it at all. Unlike
32 other mail tools, OfflineIMAP features a multi-threaded
33 synchronization algorithm that can dramatically speed up
34 performance in many situations by synchronizing several
35 different things simultaneously.
37 OfflineIMAP is FLEXIBLE; you can customize which folders
38 are synced via regular expressions, lists, or Python
39 expressions; a versatile and comprehensive configuration
40 file is used to control behavior; two user interfaces are
41 built-in; fine-tuning of synchronization performance is
42 possible; internal or external automation is supported;
43 SSL and PREAUTH tunnels are both supported; offline (or
44 "unplugged") reading is supported; and esoteric IMAP fea-
45 tures are supported to ensure compatibility with the
46 widest variety of IMAP servers.
48 OfflineIMAP is SAFE; it uses an algorithm designed to pre-
49 vent mail loss at all costs. Because of the design of
50 this algorithm, even programming errors should not result
51 in loss of mail. I am so confident in the algorithm that
52 I use my own personal and work accounts for testing of
53 OfflineIMAP pre-release, development, and beta releases.
56 OfflineIMAP operates by maintaining a hierarchy of mail
57 folders in Maildir format locally. Your own mail reader
58 will read mail from this tree, and need never know that
59 the mail comes from IMAP. OfflineIMAP will detect changes
60 to the mail folders on your IMAP server and your own com-
61 puter and bi-directionally synchronize them, copying,
62 marking, and deleting messages as necessary.
65 If you are reading this document via the "man" command, it
66 is likely that you have no installation tasks to perform;
67 your system administrator has already installed it. If
68 you need to install it yourself, you have three options: a
69 system-wide installation with Debian, system-wide instal-
70 lation with other systems, and a single-user installation.
71 You can download the latest version of OfflineIMAP from
72 http://quux.org/devel/offlineimap/.
75 In order to use OfflineIMAP, you need to have these condi-
78 o Your mail server must support IMAP. Most Internet
79 Service Providers and corporate networks do, and
80 most operating systems have an IMAP implementation
83 o You must have Python version 2.2.1 or above
84 installed. If you are running on Debian GNU/Linux,
85 this requirement will automatically be taken care
86 of for you. If you do not have Python already,
87 check with your system administrator or operating
88 system vendor; or, download it from
89 http://www.python.org/. If you intend to use the
90 Tk interface, you must have Tkiner (python-tk)
91 installed. If you intend to use the SSL interface,
92 your Python must have been built with SSL support.
94 o Have a mail reader that supports the Maildir mail-
95 box format. Most modern mail readers have this
96 support built-in, so you can choose from a wide
97 variety of mail servers. This format is also known
98 as the "qmail" format, so any mail reader compati-
99 ble with it will work with OfflineIMAP.
101 DEBIAN SYSTEM-WIDE INSTALLATION
102 If you are tracking Debian unstable, you may install
103 OfflineIMAP by simply running the following command as
106 apt-get install offlineimap
108 If you are not tracking Debian unstable, download the
109 Debian .deb package from the OfflineIMAP website and then
110 run dpkg -i to install the downloaded package. Then, go
111 to CONFIGURATION below. You will type offlineimap to
114 OTHER SYSTEM-WIDE INSTALLATION
115 Download the tar.gz version of the package from the web-
116 site. Then run these commands:
118 tar -zxvf offlineimap-x.y.z.tar.gz
122 Some systems will need to use python instead of python2.2.
123 Next, proceed to configuration. You will type offlineimap
124 to invoke the program.
126 SINGLE-ACCOUNT INSTALLATION
127 Download the tar.gz version of the package from the web-
128 site. Then run these commands:
130 tar -zxvf offlineimap-x.y.z.tar.gz
133 When you want to run OfflineIMAP, you will issue the cd
134 command as above and then type ./offlineimap; there is no
135 installation step necessary.
138 OfflineIMAP is regulated by a configuration file that is
139 normally stored in ~/.offlineimaprc. OfflineIMAP ships
140 with a file named offlineimap.conf that you should copy to
141 that location and then edit. This file is vital to proper
142 operation of the system; it sets everything you need to
143 run OfflineIMAP. Full documentation for the configuration
144 file is included within the sample file.
147 Most configuration is done via the configuration file.
148 Nevertheless, there are a few options that you may set for
151 -1 Disable all multithreading operations and use
152 solely a single-thread sync. This effectively sets
153 the maxsyncaccounts and all maxconnections configu-
154 ration file variables to 1.
157 Overrides the accounts section in the config file.
158 Lets you specify a particular account or set of
159 accounts to sync without having to edit the config
160 file. You might use this to exclude certain
161 accounts, or to sync some accounts that you nor-
165 Specifies a configuration file to use in lieu of
166 the default, ~/.offlineimaprc.
168 -d Enables IMAP protocol stream and parsing debugging.
169 This is useful if you are trying to track down a
170 malfunction or figure out what is going on under
171 the hood. I suggest that you use this with -1 in
172 order to make the results more sensible. Note that
173 this output will contain full IMAP protocol in
174 plain text, including passwords, so take care to
175 remove that from the debugging output before send-
176 ing it to anyone else.
178 -o Run only once, ignoring any autorefresh setting in
182 Show summary of options.
185 Specifies an alternative user interface module to
186 use. This overrides the default specified in the
187 configuration file. The UI specified with -u will
188 be forced to be used, even if its isuable() method
189 states that it cannot be. Use this option with
192 The pre-defined options are Tk.TKUI (a graphical
193 interface) and TTY.TTYUI (a text-mode interface).
196 Here is an example configuration for a particularly com-
197 plex situation; more examples will be added later.
199 MULTIPLE ACCOUNTS WITH MUTT
200 This example shows you how to set up OfflineIMAP to syn-
201 chronize multiple accounts with the mutt mail reader.
203 Start by creating a directory to hold your folders:
206 In your ~/.offlineimaprc, specify this:
207 accounts = Personal, Work
209 Make sure that you have both a [Personal] and a [Work]
210 section, with different localfolder pathnames and enable
213 In each account section, do something like this:
214 localfolders = ~/Mail/Personal
216 Add these lines to your ~/.muttrc:
217 source ~/path-to-mbnames-muttrc-mailboxes
218 folder-hook Personal set from="youremail@personal.com"
219 folder-hook Work set from="youremail@work.com"
220 set mbox_type=Maildir
221 set folder=$HOME/Mail
222 set spoolfile=+Personal/INBOX
227 If you get one of some frequently-encountered or confusing
228 errors, please check this section.
230 UID validity problem for folder
231 IMAP servers use a unique ID (UID) to refer to a specific
232 message. This number is guaranteed to be unique to a par-
233 ticular message FOREVER. No other message in the same
234 folder will ever get the same UID. UIDs are an integral
235 part of OfflineIMAP's synchronization scheme; they are
236 used to match up messages on your computer to messages on
239 Sometimes, the UIDs on the server might get reset. Usu-
240 ally this will happen if you delete and then recreate a
241 folder. When you create a folder, the server will often
242 start the UID back from 1. But OfflineIMAP might still
243 have the UIDs from the previous folder by the same name
244 stored. OfflineIMAP will detect this condition and skip
245 the folder. This is GOOD, because it prevents data loss.
247 You can fix it by removing your local folder and cache
248 data. For instance, if your folders are under ~/Folders
249 and the folder with the problem is INBOX, you'd type this:
251 rm -r ~/Folders/INBOX
252 rm ~/.offlineimap/AccountName/INBOX
254 (replacing AccountName with the account name as specified
257 Next time you run OfflineIMAP, it will re-download the
258 folder with the new UIDs. Note that the procedure speci-
259 fied above will lose any local changes made to the folder.
261 Some IMAP servers are broken and do not support UIDs prop-
262 erly. If you continue to get this error for all your
263 folders even after performing the above procedure, it is
264 likely that your IMAP server falls into this category.
265 OfflineIMAP is incompatible with such servers. Using
266 OfflineIMAP with them will not destroy any mail, but at
267 the same time, it will not actually synchronize it either.
268 (OfflineIMAP will detect this condition and abort prior to
272 OTHER FREQUENTLY ASKED QUESTIONS
273 There are some other FAQs that might not fit into another
274 section of this document, and they are enumerated here.
276 What platforms does OfflineIMAP run on?
277 It should run on most platforms supported by
278 Python, which are quite a few.
280 I'm using Mutt. Other IMAP sync programs require me to use
281 set maildir_trash=yes . Do I need to do that with
283 No. OfflineIMAP is smart enough to figure out mes-
284 sage deletion without this extra crutch. You'll
285 get the best results if you don't use this setting,
288 How do I specify the names of my folders?
289 You do not need to. OfflineIMAP is smart enough to
290 automatically figure out what folders are present
291 on the IMAP server and synchronize them. You can
292 use the folderfilter and foldertrans configuration
293 file options to request certain folders and rename
294 them as they come in if you like.
296 How can I prevent certain folders from being synced?
297 Use the folderfilter option in the configuration
300 How can I add or delete a folder?
301 OfflineIMAP does not currently provide this fea-
302 ture, but if you create a new folder on the IMAP
303 server, it will be created locally automatically.
305 Are there any other warnings that I should be aware of?
306 Yes; see the NOTES section below.
308 What is the mailbox name recorder (mbnames) for?
309 The Mutt mail reader is not capable of automati-
310 cally determining the names of your mailboxes.
311 OfflineIMAP can help it (or many other) programs
312 out be writing these names out in a format you
313 specify. See the example offlineimap.conf file for
316 Can I synchronize multiple accounts with OfflineIMAP?
317 Sure. Just name them all in the accounts line in
318 the general section of the config file, and add a
319 per-account section for each one.
321 Does OfflineIMAP support POP?
322 No. POP is not robust enough to do a completely
323 reliable multi-machine synchronization like
324 OfflineIMAP can do. OfflineIMAP will not support
327 Do you support mailbox formats other than Maildir?
328 Not at present. There is no technical reason not
329 to; just no demand yet. Maildir is a superior for-
332 [technical] Why are your Maildir message filenames so
334 OfflineIMAP has two relevant principles: 1) never
335 modifying your messages in any way and 2) ensuring
336 100% reliable synchronizations. In order to do a
337 reliable sync, OfflineIMAP must have a way to
338 uniquely identify each e-mail. Three pieces of
339 information are required to do this: your account
340 name, the folder name, and the message UID. The
341 account name can be calculated from the path in
342 which your messages are. The folder name can usu-
343 ally be as well, BUT some mail clients move mes-
344 sages between folders by simply moving the file,
345 leaving the name intact.
347 So, OfflineIMAP must store both a UID folder ID.
348 The folder ID is necessary so OfflineIMAP can
349 detect a message moved to a different folder.
350 OfflineIMAP stores the UID (U= number) and an
351 md5sum of the foldername (FMD5= number) to facili-
354 What is the speed of OfflineIMAP's sync?
355 OfflineIMAP versions 2.0 and above contain a multi-
356 threaded system. A good way to experiment is by
357 setting maxsyncaccounts to 3 and maxconnections to
358 3 in each account clause.
360 This lets OfflineIMAP open up multiple connections
361 simultaneously. That will let it process multiple
362 folders and messages at once. In most cases, this
363 will increase performance of the sync.
365 Don't set the number too high. If you do that,
366 things might actually slow down as your link gets
367 saturated. Also, too many connections can cause
368 mail servers to have excessive load. Administra-
369 tors might take unkindly to this, and the server
370 might bog down. There are many variables in the
371 optimal setting; experimentation may help.
373 An informal benchmark yields these results for my
376 10 minutes with MacOS X Mail.app "manual cache"
377 5 minutes with GNUS agent sync
378 20 seconds with OfflineIMAP 1.x
379 9 seconds with OfflineIMAP 2.x
380 3 seconds with OfflineIMAP 3.x "cold start"
381 2 seconds with OfflineIMAP 3.x "held connection"
384 o Internet Message Access Protocol version 4rev1
385 (IMAP 4rev1) as specified in RFC2060
387 o Maildir as specified in http://www.qmail.org/qmail-
388 manual-html/man5/maildir.html and
389 http://cr.yp.to/proto/maildir.html.
391 o Standard Python 2.2.1 as implemented on POSIX-com-
395 DELETING LOCAL FOLDERS
396 OfflineIMAP does a two-way synchronization. That is, if
397 you make a change to the mail on the server, it will be
398 propogated to your local copy, and vise-versa. Some peo-
399 ple might think that it would be wise to just delete all
400 their local mail folders periodically. If you do this
401 with OfflineIMAP, remember to also remove your local sta-
402 tus cache (~/.offlineimap by default). Otherwise,
403 OfflineIMAP will take this as an intentional deletion of
404 many messages and will interpret your action as requesting
405 them to be deleted from the server as well. (If you don't
406 understand this, don't worry; you probably won't encounter
410 There is an OfflineIMAP mailing list available.
412 To subscribe, send the text "Subscribe" in the subject of
413 a mail to offlineimap-request@complete.org. To post, send
414 the message to offlineimap@complete.org.
417 Should be reported to the author at the address specified
421 OfflineIMAP is Copyright (C) 2002 John Goerzen.
423 This program is free software; you can redistribute it
424 and/or modify it under the terms of the GNU General Public
425 License as published by the Free Software Foundation;
426 either version 2 of the License, or (at your option) any
429 This program is distributed in the hope that it will be
430 useful, but WITHOUT ANY WARRANTY; without even the implied
431 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
432 PURPOSE. See the GNU General Public License for more
435 You should have received a copy of the GNU General Public
436 License along with this program; if not, write to:
438 Free Software Foundation, Inc.
441 Boston, MA 02111-1307
445 OfflineIMAP, its libraries, documentation, and all
446 included files, except where noted, was written by John
447 Goerzen <jgoerzen@complete.org> and copyright is held as
448 stated in the COPYRIGHT section.
450 OfflineIMAP may be downloaded, and information found, from
451 its homepage via either Gopher or HTTP:
453 gopher://quux.org/1/devel/offlineimap
454 http://quux.org/devel/offlineimap
462 John Goerzen July 12, 2002 OFFLINEIMAP(1)