Easy, scriptable document scanning for Linux: ADF duplex batches in, searchable (OCRed) PDFs out.
It consists of two components, shipped as two Python packages, so servers and scripts can install the CLI alone while desktops get the whole experience:
scanmole: CLI scanning engine.scanmole-gui: GTK4/libadwaita frontend (depends onscanmole). A thin subprocess wrapper around the CLI using its--jsonevent protocol; it contains no scanning logic itself.
⭐ Found this useful? Support open-source and star this project:
Main features:
- Scan a stack of paper into one searchable PDF with a single command: duplex batch, blank backsides dropped, OCR text layer, archival PDF/A output by default.
- Automatic page size detection crops every page to the detected paper edges, falling back to conservative framing around the printed content where a device hides the paper boundary, so receipts come out receipt-sized and mixed stacks need no set-up. When content fits A4 and US Letter alike,
--auto-size-preference iso|north-americandecides the ambiguity (ISO by default). - Small files by default: 1-bit black-and-white at 300 dpi lands at roughly 100 KB per A4 text page, and ocrmypdf shrinks that further where
jbig2encis installed. - Works with anything SANE can drive, including driverless eSCL devices via
sane-airscan. Device capabilities are probed and mapped instead of hardcoded, and devices without a native 1-bit mode get software binarization automatically. - Automation-grade CLI with defined exit codes, filename templates and a versioned JSON event protocol; interrupted batches can be rebuilt from the preserved page images without rescanning the paper.
- Easy-to-use GTK4/libadwaita GUI on top of the same engine, with a live filename preview and translations (German included).
ScanMole needs Python ≥ 3.12. Its two packages are available on PyPI: scanmole (the CLI) and scanmole-gui (the desktop frontend, pulls the CLI automatically).
Desktop (CLI + GUI), using uv (recommended): the GUI uses the distribution's PyGObject/GTK (see the packages below), so its virtualenv must see the system site packages:
uv venv --system-site-packages ~/.venvs/scanmole
source ~/.venvs/scanmole/bin/activate
uv pip install scanmole-guiTip: after the first scanmole-gui start, the settings dialog can install a menu entry, so later starts come straight from the desktop's application grid without any venv activation.
Server or scripting (CLI only): the CLI is pure stdlib and installs into any isolated environment:
uv tool install scanmoleUsing pip or pipx instead of uv:
pipx install --system-site-packages scanmole-gui # desktop
pip install scanmole # CLI onlyFor development installs from a repository checkout, see DEVELOPMENT.md.
ScanMole's runtime shells out to external tools, which come from distribution packages. Install them as follows (on a CLI-only machine, the GTK/PyGObject packages at the end of each list can be skipped):
Only Debian 13+ and Ubuntu 24.04+ are supported (older releases lack the required Python ≥ 3.12):
sudo apt install sane-utils sane-airscan img2pdf ocrmypdf \
tesseract-ocr tesseract-ocr-deu tesseract-ocr-osd jbig2enc \
python3-gi gir1.2-gtk-4.0 gir1.2-adw-1sudo dnf install sane-backends sane-airscan img2pdf ocrmypdf \
tesseract tesseract-langpack-deu tesseract-osd \
python3-gobject gtk4 libadwaitaFor smaller PDFs, it is highly recommended to also install jbig2enc (ocrmypdf picks it up automatically). Fedora does not package it (last checked: Fedora 44, 2026-Q3; a leftover of the long-expired JBIG2 encoding patents), so build it from source:
sudo dnf install gcc-c++ automake libtool leptonica-devel zlib-devel
git clone https://github.com/agl/jbig2enc.git /tmp/jbig2enc
cd /tmp/jbig2enc
./autogen.sh && ./configure && make
sudo make install # installs the jbig2 binary under /usr/local/binUpdating works the same way; the leading line reuses the clone when it still exists and starts fresh otherwise (/tmp does not survive a reboot):
git -C /tmp/jbig2enc pull || git clone https://github.com/agl/jbig2enc.git /tmp/jbig2enc
cd /tmp/jbig2enc
./autogen.sh && ./configure && make
sudo make installDevice-specific packages, network configuration and the list of verified units are collected under Devices.
scanmole --list-devices # what SANE sees (webcams/v4l are ignored)
scanmole # ADF duplex, lineart, 300 dpi, auto size, deu+eng OCR
# -> ./2026-08-15_scan_001.pdf (auto-numbered)
scanmole '{YYYY}-{MM}_scan_{NN}' # template -> ./2026-08_scan_01.pdf
scanmole -o invoice.pdf --mode gray -r 300 -l deu+eng
scanmole --source flatbed --no-ocr --keep-blanks draft
scanmole --from-images pages/*.png -o rebuild.pdf # pipeline without a scannerOutput names may contain placeholders, in the CLI and the GUI alike: {YYYY}, {MM}, {DD} (date), {hh}, {mm}, {ss} (time), {N}/{NN}/... (zero-padded auto-increment, bumped until the name is free) and {device}; the default is {YYYY}-{MM}-{DD}_scan_{NNN}.pdf.
Run scanmole --help for the full list of options. Common examples:
scanmole -r 300 'contract_{YYYY}-{MM}-{DD}_{NN}' # higher dpi for small print
scanmole --source adf --keep-blanks # single-sided stack, keep every page
scanmole --mode gray -l deu --no-pdfa notes # grayscale, German-only OCR, plain PDF
scanmole --keep-images /tmp/pages -v receipts # keep page images, verbose logWhat if my scanner acts up, for example wrong page sizes in auto mode, surviving blank pages, or a badly mapped mode? Every device behaves a little differently at the edges of a scan, and we can usually fix it from a few captured files alone: see reporting scanner problems and device quirks for exactly what to include.
Start the GUI from the environment set up in Installation:
uv run scanmole-guiThe settings dialog can install a menu entry (.desktop file) for your user, so later starts work straight from the desktop's application grid.
scanmole-gui is a form over the same engine with the same defaults. It covers and presents the CLI features in an easy-to-use way. The Scan button turns into Cancel while a batch runs, a collapsible log shows the underlying CLI output, and a result bar opens the finished PDF or its folder. The GUI remembers the last used form values and the window size in ~/.config/scanmole/gui.json and restores them on the next start.
| Code | Meaning |
|---|---|
0 |
Success: PDF written. |
1 |
Unexpected internal error. |
2 |
Usage or input error: bad arguments, invalid page size, conflicting options. No PDF was produced. |
3 |
Acquisition failure: scanimage failed, no usable device, device vanished mid-batch, or a device probe timed out. |
4 |
Missing external tool: scanimage, img2pdf or ocrmypdf is not installed. |
5 |
Processing failure: img2pdf or ocrmypdf failed after successful acquisition. Scanned pages are preserved in the work directory (path in the error message), so the batch can be rebuilt with --from-images instead of rescanning the paper. |
6 |
Nothing to scan: feeder empty, or every page was blank. Not a malfunction; no PDF was produced. |
130 |
Interrupted (SIGINT). |
143 |
Terminated (SIGTERM), e.g. a GUI cancel. |
One JSON object per line on stdout; human-readable log on stderr:
{"event":"hello","version":"1.0.0"}
{"event":"devices","devices":[{"device":"...","vendor":"...","model":"...","type":"..."}]}
{"event":"start","device":"...","source":"adf-duplex","mode":"lineart","resolution":300,"page_size":"a4","output":"..."}
{"event":"settings","device":"...","source":"ADF Duplex","mode":"Lineart","resolution":300}
{"event":"page","n":1,"file":"...","blank":false,"mean":0.87}
{"event":"scan_done","total":5,"kept":4,"blanks":1}
{"event":"ocr_start","lang":"deu"}
{"event":"done","output":"out.pdf","pages":4,"bytes":812345,"seconds":41.2}
{"event":"error","message":"...","code":3}
hello opens every --json run and carries the CLI version, which is also the API version (SemVer): a frontend and the CLI are compatible as long as their major versions match (from 1.0.0 on). start carries the requested settings; settings (scanner runs only) reports the values actually negotiated with the SANE backend. error.code mirrors the process exit code. This protocol, the option names and the exit codes are the compatibility boundary for any frontend or reimplementation; the authoritative definition is the CLI contract in ARCHITECTURE.md.
Anything SANE can drive should work without ScanMole knowing the model; vendor specifics and the verified units are collected here.
Modern Brother devices (e.g. the Brother ADS-4550W) work driverless via sane-airscan (eSCL) and need no additional packages or configuration beyond the dependencies from Installation.
Older devices without eSCL support (e.g. the Brother ADS-2600W) need Brother's proprietary brscan4/brscan5 driver packages from the Brother support site; network devices must additionally be registered with brsaneconfig4/brsaneconfig5.
Modern Epson document scanners (DS/ES/WorkForce series, e.g. the Epson DS-730N) use the epsonds backend. If your device is not recognized, try one of the following; epsonds does no discovery over the network:
-
Add a line
net <ip-address>to/etc/sane.d/epsonds.conf; the device then appears asepsonds:net:.... -
Alternatively these devices speak WSD via
sane-airscan. If discovery does not pick the scanner up, pin the endpoint in the[devices]section of/etc/sane.d/airscan.conf, copying the lineairscan-discoverreports.[devices] "<device name, e.g. EPSON DS-730N>" = http://<ip-address>:80/WDP/SCAN, WSD
Do not use an epson2:net:... entry that may show up alongside: the epson2 backend covers older flatbeds and misdetects DS models over the network (as a flatbed named "PID", failing with an I/O error at scan start).
ScanSnap devices (e.g. the ScanSnap iX500; formerly sold under the Fujitsu brand, Ricoh products today) use the stock SANE fujitsu backend over USB. They need no additional packages or configuration beyond the dependencies from Installation.
The following devices are regularly used with ScanMole and were verified with real batches:
| Device | Connection | SANE backend | Notes | Known limitations |
|---|---|---|---|---|
| Brother ADS-4550W | USB (via ipp-usb) and network | airscan (eSCL, driverless) |
Duplex ADF. Offers only Color/Gray, so 1-bit output comes from ScanMole's software conversion. | None known. |
| Canon CanoScan LiDE 220 | USB | genesys |
Flatbed. Feeder requests degrade to a single flatbed scan; 1-bit output comes from ScanMole's software conversion. | None known. |
| Epson DS-730N | Network | epsonds (see Epson) |
Duplex ADF, native 1-bit. | Ignores its hardware auto-crop command over the network; ScanMole's auto page size compensates by sizing each page from its content. |
| ScanSnap iX100 | USB | fujitsu |
Portable single-side sheet feeder, native 1-bit. | None known. |
| ScanSnap iX500 | USB | fujitsu |
Duplex ADF, native 1-bit, hardware paper-edge detection. | None known. |
Every listed device has its captured capability listing pinned in the test suite (tests/fixtures/scanimage-A/), so its option mapping stays regression-tested without the hardware. If your device works too (or does not), reporting it helps this list grow.
If a USB scanner does not show up in scanimage -L:
- Check that the needed packages are installed (see Installation):
sane-backendsprovidesscanimageandsane-find-scanner,sane-airscanprovides the driverless eSCL route andairscan-discover,usbutilsprovideslsusb. - Check
lsusb. If the scanner is missing there too, the problem is cabling, power or the USB port, not software. - Run
sane-find-scanner -q. It talks raw USB without any backend; if it finds the device whilescanimage -Lstays empty, the cause is permissions or a disabled backend. - Permissions: SANE grants access to locally logged-in desktop users. After the first plug-in, replug the device and log out and in once so the udev ACLs apply. Over ssh or headless there is no desktop session ("works locally, fails over ssh"); that needs a udev rule granting access to a
scannergroup. - Check
/etc/sane.d/dll.conf: the line for your vendor's backend must not be commented out (Canonpixma/canon_dr, Epsonepsonds/epson2, ScanSnapfujitsu; the backend keeps its historic name). - Network-capable devices from roughly 2015 on usually speak eSCL and work driverless via
sane-airscan: make sureavahi-daemonis running and check whatairscan-discoverfinds. Worth trying even when a device's USB route fails. - Vendor drivers (Canon
scangearmp2, Epsonepsonscan2, Brotherbrscan4/brscan5) are the last resort for devices without an in-tree backend or eSCL support.
See CONTRIBUTING.md: Report scanner problems and device quirks.
The defaults are already tuned for small files: 1-bit black-and-white (lineart) at 300 dpi compresses losslessly to roughly 100 KB per A4 text page. Devices without a native 1-bit mode need no special handling; ScanMole converts their gray output in software automatically.
To keep files small:
- Stay with the 300 dpi black-and-white default for usual documents. Use
--mode grayor--mode coloronly when a document really needs it (photos, stamps, faint or colored originals): they store 8 or 24 bits per pixel instead of 1, and sizes explode. The same goes for resolutions above 300 dpi, since data grows quadratically with dpi. For wholly faint originals such as thermal-paper receipts or washed-out copies, the GUI's "B/W (faint)" mode (CLI:--lineart-threshold auto) keeps the small 1-bit output; it applies one guarded threshold per page, so a page mixing normal print with a much fainter region can still lose the faint part, and Gray remains the reliable choice for those. - Use
-r 200for documents where quality matters less; it roughly halves the data. Where no text layer is needed either,--no-ocrskips OCR entirely. - Highly recommended: make sure
jbig2encis installed. ocrmypdf detects it automatically during its optimization pass and recodes 1-bit pages losslessly to a fraction of their size.command -v jbig2shows whether it is present; if it prints nothing, follow the installation instructions.
Duplex scanning reads both sides of every sheet, and ScanMole drops a page as blank when its mean brightness is above 0.995, i.e. when less than 0.5% of it is "ink". The mean is measured over the cropped page, or over the detected content area on frames still at the full scan window, so window padding cannot hide sparse content. That is what removes the empty backsides of single-sided documents, but a page holding only a line or two sits close to the cutoff and can land on either side of it. Both failure directions have knobs: if a page with sparse or faint content was dropped, raise --blank-threshold towards 1, use --keep-blanks to keep every page while blanks are still counted, or set --blank-threshold 0 to switch the classification off entirely; in the GUI, disable "Skip blank pages" (it maps to --keep-blanks). If a truly blank page survives, something dark is pulling its mean down, typically punch holes, staple shadows or a skewed scan showing the scan-bed edge; if tuning the threshold does not fix it, report the device quirk.
See CONTRIBUTING.md for how to report issues and submit changes. Translations are welcome.
This project's functionality is mature, so there might be little activity on the repository in the future. Don't get fooled by this, the project is under active maintenance and used on a daily basis by the maintainers.
Copyright (c) 2026 foundata GmbH (https://foundata.com)
This project is licensed under the GNU General Public License v3.0 or later (SPDX-License-Identifier: GPL-3.0-or-later), see LICENSES/GPL-3.0-or-later.txt for the full text.
The REUSE.toml file provides detailed licensing and copyright information in a human- and machine-readable format. This includes parts that may be subject to different licensing or usage terms, such as third-party components. The repository conforms to the REUSE specification. You can use reuse spdx to create a SPDX software bill of materials (SBOM).
- ScanSnap is a trademark of PFU Limited, a Ricoh Group company (ScanSnap scanners were sold under the Fujitsu brand until 2023)
- Fujitsu is a trademark of Fujitsu Limited
- Brother is a trademark of Brother Industries, Ltd
Their use here is purely descriptive and does not imply any affiliation with or endorsement by the trademark holders.
This project was created and is maintained by foundata GmbH.