Download

Unzip. That's the whole install.

A trimmed Java runtime ships inside, so there's no Java and no Python to install. Every conversion happens on your machine.

macOS Apple Silicon · arm64 Download .dmg v1.0.2 · 121 MB · signed & notarized
macOS Intel · x86_64 Download .dmg v1.0.2 · 122 MB · signed & notarized
Windows x64 Download .zip v1.0.2 · 116 MB · unsigned

First launch. The macOS packages are signed with a Developer ID and notarized by Apple — double-click and they open, no override needed. The Windows package is unsigned, so SmartScreen warns once: click "More info" → "Run anyway" and it won't ask again.

What's in the package

Four programs
Command line, desktop app, the long-running web service and the MCP server, sharing one set of dependencies
Java runtime
Trimmed with jlink — only the modules actually used
Working folders
raw/ for input, output/ for results and config.toml for defaults, all next to the executable
Not included
The OCR service. It's heavy (a few GB), so you install it separately when you need it — see below

Install with pip

You'll need Python 3.10 or later and Java 11 or later. Java is required — the engine doing the layout analysis is written in Java.

$ pip install "aimorsel[all]"   # [all] = docx/xlsx/pptx/image input + GUI drag & drop + damaged-PDF repair
$ java -version                 # check Java is there
$ morsel --version

The package is aimorsel (PyPI); pip install morsel is an alias that installs the same package. You get the morsel command right away; morsel gui / morsel web / morsel mcp start the other three programs.

Install from source

$ git clone https://github.com/aimorsel/aimorsel.git
$ cd aimorsel
$ pip install -e ".[all]"
$ morsel --version

Only the core engine and the fallback net are required; everything else is an optional extra: a missing library only affects the feature it powers, and the error tells you exactly what to install. HTML parsing uses the standard library and needs nothing extra.

Scans and images: install OCR separately

Scans and images have no text layer, so getting text out of them needs the OCR service. It runs locally as a separate service, installs into its own environment, and uninstalls by deleting that folder. 

$ morsel --setup-ocr              # create env, install, start
$ morsel --setup-ocr-lang "de,en" # match your documents
$ morsel --stop-ocr

Match the language. In testing this mattered more than anything else: running a Chinese model over German documents wrecked the diacritics and dropped whole lines; switching to de,en fixed most of it. A mixed-language batch needs to be split by language.

Know these limits first

  • OCR output is for finding things, not for faithful reproduction. Printed body text is reliable, but formulas are largely lost, handwritten marks are ignored, and very small type drops lines.
  • Borderless tables are hit and miss. The engine finds tables by their borders by default; borderless ones need the enhanced table mode.
  • Broken font encodings in a PDF produce garbled text. That's a problem in the source file, and no parser can recover it.
  • The web service has no access control. It binds to localhost by default. Don't expose it to an untrusted network.