FileMorph

Open-source file conversion & compression you can read, run, and self-host.

Convert images, documents, audio, video, and spreadsheets; compress images to a target size. AGPL-3.0, EU-hostable, stateless. Web UI + REST API. The full engine is free with no feature gates — self-host it via Docker, or use the hosted instance at filemorph.io. Integrable by any service via REST API.

---

What is FileMorph?

FileMorph is an open-source file conversion service with two interfaces:

• Web UI — drag-and-drop files in the browser, pick a format, download the result
• REST API — send files programmatically, integrate into any application or workflow

┌─────────────────────────────────────────────────────────┐
│  FileMorph        Tools  Self-Hosted  API Docs  GitHub  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│              Convert & Compress Files                   │
│ Images · PDF · Documents · Audio · Video · Spreadsheets │
│                                                         │
│            [ Convert ]  [ Compress ]                    │
│                                                         │
│     ┌─────────────────────────────────────────┐         │
│     │              ⬆                          │         │
│     │     Drag & drop your files here         │         │
│     │   or click to browse  (multi-file)      │         │
│     │                                         │         │
│     │  HEIC · HEIF · JPG · PNG · WebP · AVIF  │         │
│     │  BMP · TIFF · GIF · ICO · DOCX · PDF    │         │
│     │  TXT · MD · HTML · EML · XLSX · CSV     │         │
│     │  JSON · MP4 · MOV · AVI · MKV · WebM    │         │
│     │  FLV · WMV · MP3 · WAV · FLAC · OGG     │         │
│     │  M4A · AAC · WMA · OPUS                 │         │
│     └─────────────────────────────────────────┘         │
│                                                         │
│     Or choose directly ────────────────────────         │
│     PDF tools                                           │
│     [Compress PDF] [JPG to PDF] [Word to PDF]           │
│     [Split PDF] [Extract PDF pages] [Insert PDF pages]  │
│     Images                                              │
│     [HEIC to JPG] [Compress image (KB/MB)]              │
│     More tools                                          │
│     [Video to GIF]                                      │
│     All tools →                                         │
│                                                         │
│     Target Format:  [ JPG                  ▼ ]          │
│     Quality:        ████████░░  85%                     │
│                                                         │
│                  [ Convert ]                            │
│                                                         │
└─────────────────────────────────────────────────────────┘

Authentication is via the X-API-Key request header for the REST API, or via the dashboard-stored key (per-browser, not shown in the form itself) for the Web UI.

---

Editions

FileMorph runs in three editions, all built from this repository:

Edition	Where	What you get
Community	Self-hosted (Docker, source)	File conversion + compression, REST API, single-user API-key auth
Cloud SaaS	filemorph.io	Community features + user accounts (JWT), tier quotas, admin cockpit; Stripe billing ships too, but filemorph.io has no paid plans
Compliance	Self-hosted with commercial licence	Cloud-Edition features + tamper-evident audit log (SHA-256 hash chain), X-Output-SHA256 integrity header, PDF/A-2b output (CI gate validated against veraPDF for a worst-case fixture), default-on metadata strip (EXIF/XMP/IPTC in images, tags and chapters in video, all but the music tags in audio), X-Data-Classification header, self-service account deletion, signed images (cosign) + cryptographically signed releases. For DACH Behörden, Krankenhäuser, and Anwaltskanzleien.

PII redaction (commercial add-on, app/ee/, inert unless AI_OPERATIONS_ENABLED): detect + remove structured PII — IBAN, email, phone, IPv4, payment card — from TXT/DOCX/XLSX, with fail-closed verification. Honest scope: no free-text names/addresses yet (no NER), no PDF. See docs/pii-redaction.md. It is not a format conversion, so it is absent from the Supported Formats table.

PDF/A-2b output, the default-on metadata strip and the X-Output-SHA256 header are part of the AGPL engine and work in every edition; the hash-chained audit log is AGPL code too and records whenever DATABASE_URL is set (Cloud overlay). What the Compliance Edition adds is the commercial licence, a support SLA and a liable contact — see COMMERCIAL-LICENSE.md. Self-hosted, you run FileMorph yourself: there is no data processing on your behalf, so no DPA is needed (docs/dpa-template.md § 1).

The README and docs/ are written for the Community edition. The Cloud-Edition features (account registration, Stripe checkout, admin cockpit, email verification, account deletion) ship in the same codebase but stay dormant unless you enable the Cloud overlay (see Quickstart Option B below) — see docs/self-hosting.md for the full stack and docs/security-overview.md for the defensive-transparency overview. The Compliance-Edition contract

• commercial licence are described at /enterprise (live on filemorph.io) and COMMERCIAL-LICENSE.md.

---

Pricing & positioning

FileMorph is free and self-hostable forever under AGPL-3.0, with no feature gates. The hosted service on filemorph.io is free as well; the Compliance Edition adds a commercial licence plus contracts for regulated administration.

Hosted service (filemorph.io) — free, with fair limits. There are no paid plans; a free account adds larger files, batches and an API key. Self-hosting is always free, with the limits you set.

Use	File size	Batch	API calls/mo	Concurrency
Without an account	30 MB	1	not metered	1
Free account	100 MB	10	1,000	1

Everyone shares the server's parallel slots (MAX_GLOBAL_CONCURRENCY), and the per-minute rate limit is the same with or without an account.

Compliance Edition (self-hosted + commercial licence) — for DACH Behörden, Krankenhäuser, Anwaltskanzleien; data stays behind your firewall. Prices on request.

Tier	Scope
Starter	1 server, ≤ 50 staff
Standard	3 servers, ≤ 2,000 staff
Enterprise	unlimited servers, custom SLA

Includes the commercial licence, the SHA-256 audit log, PDF/A-2b (veraPDF CI-gated), default-on metadata strip, and signed images (cosign) + SBOM. See /enterprise and COMMERCIAL-LICENSE.md. Internal use by an authority is already free under AGPL — the Compliance Edition sells accountability (SLA, a liable EU contact), not permission. The audit log, PDF/A-2b, the metadata strip and the signed images in that list are the same AGPL code and builds every edition runs.

Honest maturity: no external audit or ISO 27001 certification yet (both a Year-2 roadmap item). The newest tagged release is v1.4.0 (October 2026), with a CycloneDX SBOM and the image digest attached to the GitHub release; changes merged after it are in changelog.d/ until the next release folds them into CHANGELOG.md. Everything else above is in the repository today and auditable.

---

Supported Formats

Category	Input formats	Output formats
Images	HEIC, HEIF, JPG, JPEG, PNG, WebP, AVIF, BMP, TIFF, GIF, ICO	JPG, PNG, WebP, AVIF, BMP, TIFF, GIF, ICO, PDF
Documents	DOCX, TXT, Markdown (.md)	PDF, TXT, HTML
Web & email	HTML, EML	PDF
PDF	PDF	TXT, PDF/A-2b†
Spreadsheets	XLSX, CSV, JSON	CSV, XLSX, JSON
Audio	MP3, WAV, FLAC, OGG, M4A, AAC, WMA, Opus	MP3, WAV, FLAC, OGG, M4A, AAC, WMA, Opus
Video	MP4, MOV, AVI, MKV, WebM, FLV, WMV	MP4, MOV, AVI, MKV, WebM, FLV, WMV, GIF

Compression (quality-based or target-size, no re-encoding format change): Images: JPG, PNG, WebP, AVIF, TIFF · Video: MP4, MOV, AVI, MKV, WebM Compress mode supports both by quality % and by target size MB. Target-size compression covers the lossy image formats (JPEG, WebP, AVIF); AVIF/AV1 encode is more CPU-intensive than JPEG/WebP.

PDF tools: split a PDF into single-page files, extract a page range, compress to at most a target size, or insert a PDF, a Word file or an image at a chosen page — via the web UI (/pdf/split, /pdf/extract, /pdf/compress, /pdf/insert) or the API; see docs/formats.md. Image compression to a target size (video too, by quality) has its own page at /compress, and turning a short video into an animated GIF has one at /convert/video-to-gif. All tool pages are listed at /tools.

† Full PDF/A-2b conformance (passes veraPDF validation) requires Ghostscript on the host. The Docker image bundles it; for local-Python installs see docs/installation.md. Without Ghostscript, pdf → pdfa falls back to a markup-only output that veraPDF will reject if the source PDF has unembedded fonts.

---

Quickstart

Option A — Docker, Community Edition (recommended for self-hosting)

Requires Docker Desktop (Windows/macOS) or docker + docker compose (Linux).

git clone https://github.com/MrChengLen/FileMorph.git
cd FileMorph

Windows — double-click start.bat Linux / macOS — run ./start.sh

Both scripts build the image (first run: 2–5 min), wait for the healthcheck, print your API key from the container logs, and open the browser at http://localhost:8000. API keys live under ./data/ and survive docker compose down.

Manual start without the launcher script:

docker compose up -d
docker compose logs --tail=30 filemorph    # shows API key on first run

Stop:

docker compose down

High-fidelity DOCX → PDF (office image): the default image converts DOCX with a pure-Python pipeline (mammoth + WeasyPrint), which simplifies footnotes, headers/footers, multi-section page setup and similar Word layout. For Word-grade output, layer the office overlay on top — it adds LibreOffice (the image is about 280 MB larger):

docker compose -f docker-compose.yml -f docker-compose.office.yml up -d

FILEMORPH_OFFICE_ENGINE in .env picks the engine: auto (default) sends only complex documents to LibreOffice, libreoffice sends every DOCX, mammoth none. The pre-built image is ghcr.io/mrchenglen/filemorph:office.

Option B — Docker, Cloud Edition (user accounts + Stripe + cockpit)

The Cloud-Edition features (registration, JWT login, billing, admin cockpit, audit log, daily metrics) need a Postgres database. Layer on the Cloud overlay:

cp .env.example .env                      # then set POSTGRES_PASSWORD + JWT_SECRET
docker compose -f docker-compose.yml -f docker-compose.cloud.yml up -d

The entrypoint runs alembic upgrade head on first boot (and on every restart — idempotent). Cloud-Edition env vars (STRIPE_*, SMTP_*, CORS_ORIGINS, APP_BASE_URL, …) are documented in .env.example and in docs/self-hosting.md.

The admin cockpit (/cockpit) needs an admin account: register in the web UI, then promote that address from the command line:

docker compose -f docker-compose.yml -f docker-compose.cloud.yml exec filemorph python scripts/promote_admin.py [email protected]

Stop:

docker compose -f docker-compose.yml -f docker-compose.cloud.yml down

Option C — Local development (Windows)

Requires Python 3.11+ and Git. No Docker needed. DOCX, Markdown, HTML and EML → PDF go through WeasyPrint, which needs the GTK/Pango libraries installed on Windows, and full PDF/A-2b needs Ghostscript — see WeasyPrint's installation notes and docs/installation.md.

git clone https://github.com/MrChengLen/FileMorph.git
cd FileMorph
.\dev.ps1

On first run, dev.ps1 creates the virtual environment, copies .env.example to .env and generates your API key. On every start it runs pip install -r requirements.txt (so new dependencies arrive after a git pull) and then starts the server with live-reload at http://127.0.0.1:8000.

Optional — Desktop shortcut (double-click to start):

.\create-shortcut.ps1

This places a FileMorph shortcut on your Desktop.

---

API Usage

All conversion endpoints accept the X-API-Key header.

# Convert HEIC → JPG
curl -X POST http://localhost:8000/api/v1/convert \
  -H "X-API-Key: YOUR_KEY" \
  -F "[email protected]" \
  -F "target_format=jpg" \
  --output photo.jpg

# Compress an image to 70% quality
curl -X POST http://localhost:8000/api/v1/compress \
  -H "X-API-Key: YOUR_KEY" \
  -F "[email protected]" \
  -F "quality=70" \
  --output smaller.jpg

# List all supported conversions
curl http://localhost:8000/api/v1/formats

# Interactive Swagger docs
open http://localhost:8000/docs

→ Full API reference: docs/api-reference.md

---

Documentation

Guide	Description
Installation	Step-by-step setup for Windows and Linux
API Reference	All endpoints, parameters, response formats, error codes
API Usage Guide	Integration walkthrough: auth, batches, error handling, quotas, CORS
Self-Hosting	Docker, production deployment, reverse proxy, SSL
Security Overview	Defensive transparency: auth, validation, headers, known limits
Release Signing	How to verify release tags and container images
Formats	All supported formats with use cases and notes
Development	Add converters, run tests, project structure
Contributing	How to contribute to FileMorph

For procurement reviewers and DPOs evaluating the Compliance Edition: COMMERCIAL-LICENSE.md (dual-license model, tiers, licensing-vs-AGPL boundary) is the canonical entry point. A self-hosted deployment involves no data processing on your behalf; the Article 28 DPA skeleton in docs/dpa-template.md applies only where it does (its §1). The supporting artefacts: docs/dpa-tom-annex.md (Art. 32 TOMs), docs/records-of-processing-template.md (Art. 30 RoPA), docs/sub-processors.md, docs/threat-model.md, docs/patch-policy.md, docs/incident-response.md, docs/support-sla.md, docs/onboarding.md, docs/third-party-licenses.md, and the signature-ready docs/commercial-license-agreement-template.md.

---

Use Cases

• End users — Convert iPhone photos (HEIC) to JPG, compress images before emailing, turn Word documents into PDFs
• Organizations — Integrate the API into document management systems, portals, or upload pipelines (DSGVO-compliant when self-hosted)
• Developers — Add format conversion to any app without implementing conversion logic

---

System Requirements

Method	Requirements
Docker (Option A or B)	Docker Desktop (Windows/macOS) or docker + docker compose (Linux)
Local dev (dev.ps1)	Python 3.11+, Git; GTK/Pango for WeasyPrint (DOCX/Markdown/HTML/EML → PDF), Ghostscript (PDF/A-2b) — see installation
Linux source	Python 3.11+, ffmpeg, Cairo/Pango, Ghostscript (PDF/A-2b); libheif comes with the pillow-heif wheel

ffmpeg note: Required for audio and video conversion. Not needed for images, documents, or spreadsheets. The Docker images include ffmpeg automatically.

---

License

FileMorph is dual-licensed:

• AGPL-3.0 — free for personal use, academic use, internal company use, and open-source projects. If you host a modified version as a public network service, you must publish the source of your modifications.
• Commercial License — for closed-source SaaS, OEM / white-label, or any deployment that cannot meet the AGPL copyleft obligations. Contact [email protected].

One exception: everything under app/ee/ (the PII-redaction add-on) is licensed only under the Commercial License. Its source is published for review, but it is not AGPL and not open source.