Installation

Installation

Python 3.9 or newer is required. pipx is recommended because it keeps the application isolated while exposing its commands on your PATH.

Standard commands

pipx install imap-migration-tools

Or install into a virtual environment:

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

.env loading and OAuth provider dependencies are part of the standard installation. The historical imap-migration-tools[dotenv] spelling remains accepted but is no longer required.

Terminal interface

Install the optional beta TUI and launch it with:

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

For an existing pipx installation:

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

Encrypted OAuth caching on Linux

Persistent OAuth credentials use platform encryption and never fall back to plaintext. Linux installations may need the optional native keyring backend and distribution packages for GObject introspection, Cairo, and libsecret:

pipx install --force "imap-migration-tools[linux-keyring]"

When encrypted persistence is unavailable, authentication continues with process-local caching and displays a concise diagnostic. Consult your distribution documentation for the native PyGObject/libsecret prerequisites.

Source checkout

git clone https://github.com/JCallico/imap-migration-tools.git
cd imap-migration-tools
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[tui]"
.venv/bin/python -m pip install -r requirements.txt

Continue with Configuration or Workflows.