OfflineIMAP: a local Maildir copy of an IMAP mailbox

Why keep a copy of the mailbox when the provider already has one

The motivation is trust. The project puts it plainly: the main downside of IMAP is that you have to trust your email provider not to lose your email, and while that is unlikely it is not impossible. OfflineIMAP downloads your mailboxes as local Maildirs so you hold your own backup, and it synchronises both sides through IMAP rather than doing a one-way copy. Once the mail is local, reading it offline no longer depends on your mail reader implementing IMAP, and an attachment from an old message is still there when the network is not. That is the whole value proposition: not a better client, but a local copy that outlives the account and works without a connection. The implementation is Python, and the licence is GNU General Public License v2.0 or later.

Two-way synchronisation over IMAP into a Maildir layout

The data flow is the standard one for IMAP clients, and the layout it produces is the plain Maildir format. The repository ships two sample configuration files, offlineimap.conf and offlineimap.conf.minimal, which show how accounts and mailbox mappings are declared, and the documentation mentions a pythonfile for per-account Python logic. Nothing about the design is unusual, and that is the point: the output is an ordinary Maildir tree that any mail reader or shell command can work with. The repository root also holds the offlineimap.py entry point, a bin/ directory, contrib/ for auxiliary files, docs/, scripts/ and both test/ and tests/ directories, plus a Dockerfile and a snapcraft.yaml for packaging. Version 8.0.3 is the current release, tagged on 2026-06-08, and the last push to the repository was on 2026-06-15.

Installing through the distribution rather than with pip

The project asks you to check whether your distribution already packages OfflineIMAP before downloading anything, and on Linux and BSD that is the normal route:

apt install offlineimap3

The same section lists the equivalent commands for other systems, including zypper install offlineimap for openSUSE, dnf install offlineimap for Fedora, and for FreeBSD a search followed by installing the Python versioned package py311-offlineimap3. On Arch there is a pacman -S offlineimap package and an AUR package named offlineimap3-git. A Docker image name is given as well, offlineimap/offlineimap:latest, with a note in parentheses that the image is not published yet and the line is only an example. Release tarballs and zipballs are also published from the tags page for anyone who wants to build from source.

imaplib2 is required, everything else is optional

The dependency picture is small and clearly marked. Python 3.6 or newer is the floor, and two packages are required: rfc6555 and imaplib2 at version 3.5 or newer. The rest are optional and each buys a specific capability. keyring stores passwords in a secure way, gssapi enables Kerberos authentication, pysocks provides proxy support, portalocker is needed if you run the tool under Cygwin on Windows, and certify and urllib3 are there for Internet SSL certificate validation. The packaging metadata makes the same split explicit, with optional dependency groups named cygwin, kerberos, keyring, pysocks and testinternet, and a single console script entry point:

[project.scripts]
offlineimap = "offlineimap.init:main"

The optional groups are the reason to install from your distribution rather than from source, since a packaged build can already carry keyring or Kerberos support.

The offlineimaprc is where the work happens

Configuration is file based, and the two sample files in the repository root are the starting point: offlineimap.conf for the full example and offlineimap.conf.minimal for the short one. The documentation for the project lives on the community website, and the wiki and blog are linked from the README as well. If you would rather read the documentation locally, the repository ships the machinery for it, with a script that fetches the website sources and make targets for the other formats:

$ ./scripts/get-repository.sh website
$ cd docs
$ make html  # Requires rst2html
$ make man   # Requires a2x (http://asciidoc.org)
$ make api   # Requires sphinx

Each target names its own tool dependency, so building the HTML or the manual page locally means having rst2html, a2x or sphinx available first.

The container reads /root/.offlineimaprc and expects you to mount it

A Dockerfile sits in the repository root for running the tool in a container, and its shape is instructive about how such a tool is meant to run. It starts from a python:3 base image, installs pip and then the dependencies from requirements.txt, copies the source in and installs the application with setup.py install. The final stage is simply the base stage again, with the working directory set to /root and the command set to the installed console script:

FROM python:3 as base
CMD ["/usr/local/bin/offlineimap"]

The comment next to that command explains the contract: the program reads /root/.offlineimaprc by default, so you have to mount your configuration into the container. A multi-stage build with a separate test stage is present in the file but commented out, with a note that tests can be added there later. The build also caches dependencies by copying requirements.txt before the rest of the source.

What the project asks you to attach to a bug report

Bug reports go to the mailing list or to the GitHub project, and the README lists the information that makes a report actionable. You are asked for the system or distribution with its version, the OfflineIMAP version obtained from offlineimap -V, the Python version, the server name or domain, the command line options you used, the configuration file (offlineimaprc), the pythonfile if you use one, the logs and the error, and the steps to reproduce the failure. That last item is the one most reports omit. The same section notes that discussion, development and announcements all happen on the mailing list, which is where you subscribe, and the community has a website and a wiki alongside the repository. The project also points out that the Python 3 release is a rewrite in progress of the Python 2 code, with documentation and configuration unchanged, but with some links and packages still referring to the Python 2 version.

Where OfflineIMAP is the wrong tool

There is a real alternative approach, and it is the one most people start with: let the mail application handle IMAP itself. The difference in approach is about who owns the mailbox state. A mail client that speaks IMAP keeps its own index, its own local cache and its own idea of what has been read, and when you move to another machine you start again or sync that client. OfflineIMAP keeps no client state at all. It owns a Maildir on your disk, and the synchronisation is with the server, so the local copy stays usable by any reader, any script and any migration you have not thought of yet. The cost of that choice is disk space for a second copy of your mail and a configuration file you have to maintain. If you want mail you can read anywhere, or you want a local copy you can search from the shell, this is the tool. If you only ever read mail in one application on one machine, a client with built-in IMAP does the same job with less to install.

Editorial conclusion

OfflineIMAP fits anyone who wants their mail on their own disk, wants a mail reader that never has to speak IMAP, or needs attachments available without a connection, and who is comfortable with a plain rc file and a command line. It does not fit someone who wants their mail handled by an application that already syncs reliably, nor a Python 2 era setup that has not been migrated, since the project warns that some links and packages still point at the Python 2 release. Before adopting it, install the distribution package named offlineimap3 rather than any Python 2 era package, confirm the server exposes the folders you want, and collect offlineimap -V together with your offlineimaprc and the log output before reporting a problem, because the project asks for exactly those details.

Frequently asked questions

Official sources

1. Issues
2. OfflineIMAP/offlineimap3 on GitHub
3. README
4. Releases