PST Email Archive

Import Outlook PST files into SQLite with full-text search, natural language queries, and EML/ZIP export.

Developers: See AGENTS.md for the complete architecture, command reference, and design constraints.

Requirements

• Windows / Linux (100% cross-platform)
• Python 3.11 (required by libratom)
• No Outlook required — uses libratom + libpff for PST parsing

Quick Start

1. Install system dependencies

# Linux (Ubuntu / Debian)
sudo apt update
sudo apt install -y libpff-dev python3.11-venv python3-pip build-essential

# Windows
# Download and install Python 3.11 from https://www.python.org/downloads/
# Make sure to check "Add Python to PATH" during installation

2. Clone the repo

git clone <your-repo>
cd pst_archive

3. First run (auto-creates venv)

# Linux / macOS
./scripts/run.sh --help

# Windows (PowerShell)
.\scripts\run.ps1 --help

The first run auto-detects your OS, creates venv_linux/ or venv_win\, and installs libratom / jieba / flask / pyyaml / requests and other Python dependencies. Do not pip install manually. Do not activate the venv manually.

4. Prepare data

Put your .pst files into data/pst/.

5. Import and serve

# Linux / macOS
./scripts/run.sh import
./scripts/run.sh serve

# Windows (PowerShell)
.\scripts\run.ps1 import
.\scripts\run.ps1 serve

Open http://127.0.0.1:5000 in your browser.

If the database already exists (e.g. copied from another machine), you can skip import and just run ./scripts/run.sh serve directly.

Common Commands

./scripts/run.sh import              # Import all PSTs + rebuild FTS
./scripts/run.sh import --no-resume  # Force re-import
./scripts/run.sh serve               # Start web server
./scripts/run.sh serve --debug       # Debug mode (auto-reload)
./scripts/run.sh reindex             # Rebuild FTS index only
./scripts/run.sh search <keywords>   # CLI search
./scripts/run.sh search -n "query"   # Natural language search
./scripts/run.sh export --email-id N # Export single EML
./scripts/run.sh extract-attachments # Re-extract missing attachment blobs

On Windows, replace ./scripts/run.sh with .\scripts\run.ps1.

Directory Layout

pst-archive/
├── src/                 # Source code
├── templates/           # Flask Jinja templates (includes Vue 3 entry)
├── static/              # Static assets (vue.global.prod.js, etc.)
├── scripts/             # Runner scripts
│   ├── run.sh          # Linux / macOS runner
│   ├── run.ps1         # Windows runner
│   └── setup_venv.py   # Virtual environment bootstrap
├── build/               # PyInstaller specs and build scripts
├── data/
│   ├── pst/            # Place PST files here
│   └── db/             # SQLite database
├── config.dev.yaml      # Configuration
└── requirements.txt     # Python dependencies (referenced by setup_venv.py)

Tech Stack

• Backend: Flask + SQLite (FTS5 full-text search)
• Frontend: Vue 3 (CDN, no build step)
• PST parsing: libratom + libpff (cross-platform)

Project Status

5,201 emails imported (5,200 in FTS index), 0 errors. Supports full-text search, conversation grouping, attachment management, and batch export.

Detailed Docs

• AGENTS.md — Architecture, constraints, command reference (development guide)
• Keep both README.md and AGENTS.md in sync when changing CLI / Web behavior

License

• MIT

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

• For architecture and design constraints, read AGENTS.md first
• Run the platform runner (./scripts/run.sh or .\scripts\run.ps1) — never use bare python / pip