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
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.
