offlineimap - Man Page

Synchronize mailboxes and Maildirs both ways or one either way​.

Examples (TL;DR)

tldr.sh

Synopsis

offlineimap (options)

Description

Synchronize the accounts configured in the configuration file via IMAP​. Each account has two sides​. One of the side must be an IMAP server​. The other side can either be a Maildir or another IMAP server​.

Works with Python 3​.

Options

-h,  --help

Display summary of options​.

--version

Output version​.

-V

Output offlineimap version and additional imaplib2 information​.

--dry-run

Run in dry run mode​.

Do not actually modify any store but check and print what synchronization actions would be taken if a sync would be performed​. It will not precisely give the exact information what will happen​. If e​.g​. we need to create a folder, it merely outputs Would create folder X, but not how many and which mails it would transfer​.

--info

Output information on the configured email repositories​.

Useful for debugging and bug reporting​. Use in conjunction with the ‘-a’ option to limit the output to a single account​. This mode will prevent any actual sync to occur and exits after it output the debug information​.

-1

Limit multithreading operations and run solely a single-thread sync​.

This effectively sets the maxsyncaccounts and all maxconnections configuration file variables to 1 (the number)​.

-P <directory>

Set OfflineIMAP into profile mode​.

The program will create DIR (it must not already exist)​. As it runs, Python profiling information about each thread is logged into profiledir​. Please note: This option is present for debugging and optimization only, and should NOT be used unless you have a specific reason to do so​. It will significantly decrease program performance, may reduce reliability, and can generate huge amounts of data​. This option implies the ‘-1’ option​.

-a <account1[,account2[,​...]]>

Overrides the accounts section in the config file​.

Allows one to specify a particular account or set of accounts to sync without having to edit the config file​.

-c <path/to/configuration_file>

Specifies a configuration file to use​.

-d <type1[,type2[,​...]]>

Enables debugging for OfflineIMAP​.

This is useful if you are to track down a malfunction or figure out what is going on under the hood​. This option requires one or more debugtypes, separated by commas​. These define what exactly will be debugged, and so far include options: "imap", "thread", "maildir" or "ALL"​. The imap option will enable IMAP protocol stream and parsing debugging​. Note that the output may contain passwords, so take care to remove that from the debugging output before sending it to anyone else​. The maildir option will enable debugging for certain Maildir operations​. The use of any debug option (unless "thread" is included), implies the single-thread option ‘-1’​.

-l <path/to/file​.log>

Send logs to <file​.log>​.

-s

Send logs to syslog​.

-f <folder1[,folder1[,​...]]>

Only sync the specified folders​.

The folder names are the untranslated foldernames of the remote repository​. This command-line option overrides any folderfilter and folderincludes options in the configuration file​.

-k <[section:]option=value

Override any configuration file option​.

If "section" is omitted, it defaults to "general"​. Any underscores in the section name are replaced with spaces: for instance, to override option "autorefresh" in the "[Account Personal]" section in the config file one would use ‘-k Account_Personal:autorefresh=30’​. Repeat this option as much as necessary to redefine multiple options​.

-o

Run only once​.

Ignore any autorefresh setting in the configuration file​.

-q

Run only quick synchronizations​.

Ignore any flag updates on IMAP servers​. If a flag on the remote IMAP changes, and we have the message locally, it will be left untouched in a quick run​. This option is ignored if maxage is set​.

-u <UI>

Specifies an alternative user interface to use​.

This overrides the default specified in the configuration file​. The UI specified with ‘-u’ will be forced to be used, even if checks determine that it is not usable​. Possible interface choices are: quiet, basic, syslog, ttyui, blinkenlights, machineui​.

--delete-folder

Delete a folder on the remote repository​.

Only one account must be specified/configured for this feature to work or you must provide one account with -a​. The folder name must be provided with the remote separators (likely /) in UTF-8 if utf8foldernames is enabled or in IMAP otherwise​. E​.g​.: "Remote/folder/name"​.

--migrate-fmd5-using-nametrans

Migrate FMD5 hashes from versions prior to 6​.3​.5​.

The way that FMD5 hashes are calculated was changed in version 6​.3​.5 (now using the nametrans folder name) introducing a regression which may lead to re-uploading all messages​. Try and fix the above regression by calculating the correct FMD5 values and renaming the corresponding messages​.
Caution

Since the FMD5 part of the filename changes, this may lead to UID conflicts​. Ensure to dispose a proper backup of both the cache and the Maildir before running this fix as well as verify the results using the ‘--dry-run’ flag first​.

--mbnames-prune

Remove dangling entries for removed accounts or if mbnames is not enabled/used anymore​.

Internally, offlineimap build intermediate mbnames files​. They are added automatically when mbnames is enabled​. However, disabling accounts so they are not synced anymore does not necessarily means they should be removed from the file built by mbnames​. It is required to start offlineimap with this CLI option each time accounts are removed​. When run, any account not in the accounts configuration option are removed in the mbnames file​.

It is possible to manually remove intermediate files in <metadata>/mbnames/​.

Notice this option honors --dry-run​.

Synchronization Performance

By default, we use fairly conservative settings that are safe for syncing but that might not be the best performing one​. Once you got everything set up and running, you might want to look into speeding up your synchronization​. Here are a couple of hints and tips on how to achieve this​.

  1. Synchronize more than one account​.

    By default we only use one connection to an IMAP server​. Using 2 or even 3 speeds things up considerably in most cases​. In order to synchronize more than one account concurrently, consider starting one instance of offlineimap per account​.
    Warning
    enabling the maxsyncaccounts and maxconnections options is deprecated since it’s known to have race conditions​.

  2. Use folderfilters​.

    The quickest sync is a sync that can ignore some folders​. I sort my inbox into monthly folders, and ignore every folder that is more than 2-3 months old, this lets me only inspect a fraction of my Mails on every sync​. If you haven’t done this yet, do it :)​. See the folderfilter section in offlineimap​.conf​.

  3. The sqlite cache​.

    OfflineImap caches the state of the synchronisation to e​.g​. be able to determine if a mail has been added or deleted on either side​.

    The historical status cache was a plain text file that was writing out the complete file for each single new message (or even changed flag) to a temporary file​. If there was plenty of files in a folder this was bound to make things slow​. The latest status cache is sqlite​. This saves plenty of disk activity​.

    The historical plain status cache is not supported anymore but migrating from a very old installation using the plain text cache is still supported​. In this case, you may want to delete the old cache directory in <metadata>/Account-<account>/LocalStatus manually (the sqlite cache stands in the LocalStatus-sqlite folder)​. First, make sure you have run the new version of offlineimap for all your accounts so that the status cache was migrated​.

  4. Use quick sync​.

    A regular sync will request all flags and all UIDs of all mails in each folder which takes quite some time​. A quick sync only compares the number of messages in a folder on the IMAP side (it will detect flag changes on the Maildir side of things though)​. A quick sync on my smallish account will take 7 seconds rather than 40 seconds​. E​.g​. run a cron script that does a regular sync once a day, and does quick syncs ‘-q’ only synchronizing the ‘-f INBOX’ in between​.

  5. Turn off fsync​.

    In the [general] section you can set fsync to True or False​. If you want to play 110% safe and wait for all operations to hit the disk before continuing, you can set this to True​. If you set it to False, you lose some of that safety, trading it for speed​.

Security and SSL

By default, OfflineIMAP will connect using any method that openssl supports, that is SSLv2, SSLv3, or TLSv1​.

Do note that SSLv2 is notoriously insecure and deprecated​. Unfortunately, python2 does not offer easy ways to disable SSLv2​. It is recommended you test your setup and make sure that the mail server does not use an SSLv2 connection​. Use e​.g​. "openssl s_client -host mail​.server -port 443" to find out the connection that is used by default​.

The FAQ has an entry on how to create your own certificate and CA certificate​.

Unix Signals

OfflineImap listens to the unix signals SIGUSR1, SIGUSR2, SIGTERM, SIGINT, SIGHUP, SIGQUIT​.

Known Issues

  • XOAUTH2

    XOAUTH2 might be a bit tricky to set up​. Make sure you’ve followed the step to step guide in offlineimap​.conf​. The known bugs about Gmail are tracked at https://github​.com/OfflineIMAP/offlineimap/labels/Gmail​.

    Sometimes, you might hit one of the following error:

    • [imap]: xoauth2handler: response "{u’error': u’invalid_grant'}"
    • oauth2handler got: {u’error': u’invalid_grant'}

    In such case, we had reports that generating a new refresh token from the same client ID and secret can help​.

Google documentation on "invalid_grant". 

When you try to use a refresh token, the following returns you an
invalid_grant error:

  - Your server's clock is not in sync with network time protocol - NTP​.
  - The refresh token limit has been exceeded​.

Token expiration. 

It is possible that a granted token might no longer work​. A token might stop
working for one of these reasons:

  - The user has revoked access​.
  - The token has not been used for six months​.
  - The user changed passwords and the token contains Gmail scopes​.
  - The user account has exceeded a certain number of token requests​.

There is currently a limit of 50 refresh tokens per user account per client​. If
the limit is reached, creating a new token automatically invalidates the oldest
token without warning​. This limit does not apply to service accounts​.

See https://developers​.google​.com/analytics/devguides/config/mgmt/v3/authorization and https://developers​.google​.com/identity/protocols/OAuth2#expiration to know more​.

Main Authors

John Goerzen, Sebastian Spaetz, Eygene Ryabinkin, Nicolas Sebrecht​.

See Also

offlineimapui(7), openssl(1), signal(7), sqlite3(1)​.
http://www​.offlineimap​.org

Info

09/21/2025