IMAP Email Migration Tools

A collection of command-line tools for migrating, backing up, restoring, counting, and comparing email on IMAP servers. The tools were created for large migrations where simpler clients timed out or could not resume reliably.

They support password and OAuth2 authentication, incremental operation, Gmail labels, standard IMAP flags, local .eml backups, and destination synchronization.

These tools can copy and delete email. Test with non-critical data, verify counts and backups, and review destructive options before using them on an important account. The software is provided without warranty.

Commands

Installed command	Source entry point	Purpose
imap-migrate	src/imap_migrate.py	Copy or move email between IMAP accounts
imap-backup	src/imap_backup.py	Download an IMAP account as .eml files
imap-restore	src/imap_restore.py	Upload a local backup to an IMAP account
imap-compare	src/imap_compare.py	Compare folder counts across IMAP or local sources
imap-count	src/imap_count.py	Count messages on an account or in a local backup
imap-tools	src/tui/app.py	Configure and run all tools in a full-screen terminal interface
imap-tools-gui	src/gui/app.py	Configure and run all tools in a native desktop GUI

Legacy script names remain available as compatibility wrappers.

Installation

Python 3.10 or newer is required. Install the standard commands using pipx:

pipx install imap-migration-tools

Or use pip in a virtual environment on macOS or Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install imap-migration-tools

On Windows PowerShell:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install imap-migration-tools

On Windows Command Prompt:

py -m venv .venv
.venv\Scripts\activate.bat
python -m pip install imap-migration-tools

The standard installation supports command-line arguments, OS environment variables, and automatic .env loading. The legacy imap-migration-tools[dotenv] spelling remains accepted, but the extra is no longer necessary.

Quick start

To configure the tools with the included .env support, copy the safe template:

cp .env.example .env

Edit .env with source and destination credentials. The template enables password authentication by default; OAuth2 values are empty. Configure only one authentication method per account.

Migrate all folders:

imap-migrate

Or provide a complete account directly:

imap-migrate \
  --src-host "imap.gmail.com" \
  --src-user "source@gmail.com" \
  --src-pass "source-app-password" \
  --dest-host "imap.example.com" \
  --dest-user "destination@example.com" \
  --dest-pass "destination-password"

Back up and verify an account:

imap-backup \
  --src-host "imap.gmail.com" \
  --src-user "you@gmail.com" \
  --src-pass "app-password" \
  --dest-path "./mail-backup"

imap-compare \
  --src-host "imap.gmail.com" \
  --src-user "you@gmail.com" \
  --src-pass "app-password" \
  --dest-path "./mail-backup"

Interfaces

Python library

The installed distribution also provides the imap_services Python package. Services take explicit configuration, return structured results, and optionally publish structured progress events; unlike the command-line adapters, they do not read .env or configure logging.

from imap_services import AccountConfig, CountService, ImapTarget

account = AccountConfig(
    host="imap.example.com",
    username="person@example.com",
    password="app-password",
)
service = CountService(ImapTarget(account), on_event=lambda event: print(event.message))
result = service.run()
print(result.total)

BackupService, RestoreService, MigrationService, and ComparisonService use the same configuration and callback model. Applications may configure handlers for the imap_services logger hierarchy when diagnostic logs are needed; normal progress is delivered only through callbacks.

Full-screen terminal interface

The Textual interface provides one responsive, full-terminal application for configuring and running Count, Compare, Backup, Restore, and Migrate. Install the optional TUI dependencies with pipx:

pipx install "imap-migration-tools[tui]"

If imap-migration-tools is already installed through pipx, reinstall it with the TUI extra:

pipx install --force "imap-migration-tools[tui]"

Launch the interface with the installed command:

imap-tools

For a standard virtual environment:

python -m pip install "imap-migration-tools[tui]"
imap-tools

The interface provides a guided autosaving .env form, operation readiness guidance, live output, cancellation, and local run history.

Review the generated command in the Output panel and verify backups and counts before enabling destructive options.

The interface organizes configurations as projects: default and named projects are stored as .env files in ~/.imap-migration-tools, and a .env discovered from the current directory or its parents appears as the local project. Values use the same precedence as the scripts: per-run choices, existing OS environment variables, the project's .env, then defaults. Passwords and OAuth client secrets are masked in the form; new .env files and saved history use owner-only permissions where the platform supports them. Destructive options require typing DELETE before a run starts. Press F1 for help or F2 for the keyboard reference.

See the Terminal interface guide for responsive layouts, panel controls, ASCII mode, configuration reloads, and History behavior across multiple instances.

Basic password authentication needs no additional authentication package. OAuth2 provider dependencies are installed by the project. Encrypted persistent caching on Linux requires the linux-keyring extra and native system libraries. See Installation for platform and source setup.

Native Android application

The Android project provides a Kotlin and Jetpack Compose application for Count, Compare, Backup, Restore, and Migrate. It embeds the existing Python service engine with Chaquopy, runs user-started network operations as Android user-initiated data-transfer jobs on Android 14 and newer (with a foreground-service compatibility path on older versions), streams structured progress, supports cooperative cancellation, and keeps credentials out of persisted configuration and history.

Android builds currently target developers and CI rather than Play distribution. See the Android application guide for its architecture, build requirements, storage model, and platform execution constraints. The Google Play publication checklist tracks the separate signing, identity-provider approval, policy, store-listing, testing, and rollout work required for public distribution.

Native desktop GUI

The wxPython interface provides one native desktop workspace for configuring and running Count, Compare, Backup, Restore, and Migrate on Linux, macOS, and Windows. Install the optional desktop dependencies with pipx:

pipx install "imap-migration-tools[gui]"

If imap-migration-tools is already installed through pipx, reinstall it with the desktop extra:

pipx install --force "imap-migration-tools[gui]"

Launch the desktop application with the installed command:

imap-tools-gui

For a standard virtual environment:

python -m pip install "imap-migration-tools[gui]"
imap-tools-gui

The application provides an autosaving .env form, operation readiness guidance, confirmations, live output, cancellation, and shared local run history. It uses native GTK, Cocoa, or Windows controls, detects the operating-system theme on first launch, and provides explicit System, Light, and Dark appearance choices. View also includes persistent zoom and transparency controls; transparency depends on compositor support.

Desktop theme previews

Theme	Linux	Windows	macOS
Light
Dark

On macOS, the selected Light or Dark palette also updates native Cocoa controls, dialogs, menus, and window chrome. System mode follows the operating-system appearance.

The desktop application shares the TUI's projects, so the default and named projects are available however it is launched. Select a project or a specific file at launch when needed:

imap-tools-gui --project "Acme Corp"
imap-tools-gui --env /path/to/project/.env

Configuration precedence and secret handling match the TUI. Passwords and OAuth client secrets are masked, destructive operations require typing DELETE, and logs use the shared redaction and owner-only history storage. Review the readiness message and confirmation before starting a destructive operation.

Windows and macOS normally install wxPython from published wheels. Linux may require the distribution's wxPython package or GTK development libraries. See the Native desktop GUI guide for source installation, Linux prerequisites, appearance controls, testing, bundle creation, and platform evaluation.

Configuration essentials

Configuration precedence is:

1. Command-line arguments
2. Existing OS environment variables
3. .env values
4. Script defaults

Authentication is resolved as one choice, so a higher-precedence password cannot be displaced by a lower-precedence OAuth client ID, or vice versa. A host is an account boundary: when overriding a host, provide its username and password or OAuth client ID from the same or a higher-precedence source.

Environment-backed booleans have positive and negative CLI forms. For example:

imap-migrate --src-delete
imap-migrate --no-src-delete
imap-backup --dest-delete
imap-backup --no-dest-delete

When local, source, and destination count targets coexist, choose explicitly:

imap-count --target local
imap-count --target source
imap-count --target destination

See Configuration for all precedence, authentication, mode-selection, namespace, and boolean rules.

Common workflows

• Migration, backup, restore, count, and comparison examples
• Full-screen terminal interface
• Native desktop GUI
• Native Android app and emulator setup
• OAuth2 setup for Microsoft and Google
• Troubleshooting and operational safety
• Development, testing, and CI
• Product backlog

For large migrations, start with a count, run a non-destructive copy, compare the result, and only then consider deletion or synchronization options.

Contributing

Create a virtual environment, install the project and development requirements, then run:

make ci

See Development and AGENTS.md for the complete contributor workflow and repository conventions.

License

Licensed under the MIT License.