Skip to content


Repository files navigation

Version Build Status Coverage License Stars Activity


Backup, restore and migrate email accounts.

Quick Start

brew install imap-backup # for macOS
gem install imap-backup --no-document # for Linux
imap-backup setup


There are two types of backups:

  • Keep all (the default) - progressively saves a local copy of all emails,
  • Mirror - adds and deletes emails from the local copy to keep it up to date with the account.

What You Can Do with a Backup

  • Migrate - use the local copy to populate emails on another account. This is a once-only action that deletes any existing emails on the destination account.
  • Mirror - make a destination account match the local copy. This action can be repeated.
  • Restore - push the local copy back to the original account.

See below for a full list of commands.


Docker or Podman If you have Docker or Podman installed, the easist way to use imap-backup is via the container image.

You'll need to choose a path on your computer where your backups will be saved, we'll use ./my-data here.

If you have just one account, you can do as follows

docker run -v ./my-data:/data -ti \
  imap-backup single backup \
  --dns \
  --email --password mysecret --server \
  --path /data/

Podman will work exactly the same.

If you have multiple accounts, you can create a configuration file.

You'll need to choose a path on your computer where your configuration will be saved, we'll use ./my-config here.

First, run the menu-driven setup program to configure your accounts

docker run -ti -v ./my-config:/config -v ./my-data:/data -ti \
  --dns \
  imap-backup setup -c /config/imap-backup.json

Then, run the backup

docker run -v ./my-config:/config -v ./my-data:/data -ti \
  --dns \
  imap-backup backup -c /config/imap-backup.json
Homebrew (macOS) ![Homebrew installs](

If you have Homebrew, do this:

brew install imap-backup
As a Ruby Gem * [Rubygem]
gem install imap-backup --no-document

If that doesn't work, see the detailed installation instructions.

From Source Code If you want to use imap-backup directly from the source code, see [here](/docs/installation/


Normally you will want to backup a number of email accounts. Doing so requires the creation of a config file.

You do this via a menu-driven command line program:


imap-backup setup

As an alternative, if you only want to backup a single account, you can pass all the necessary parameters directly to the single backup command (see the single backup docs).


To use imap-backup with GMail, Office 365 and other services that require OAuth2 authentication, you can use email-oauth2-proxy. See this blog post about using imap-backup with email-oauth2-proxy.


Manually, from the command line:


Alternatively, add it to your crontab.

Backups can also be inspected, for example via local show and exported via utils export-to-thunderbird.


For a full list of available commands, run

imap-backup help

For more information about a command, run

imap-backup help COMMAND


There are a couple of performance tweaks that you can use to improve backup speed.

These are activated via two settings:

  • Global setting "Delay download writes",
  • Account setting "Multi-fetch size".

See the performance document for more information.


If you have problems:

  1. ensure that you have the latest release,
  2. run imap-backup with the -v or --verbose parameter.


See the Developer Documentation.