auto-scanner-ocr is a Rust TUI for Linux that drives a flatbed SANE scanner (e.g. HP Deskjet 1050a) and turns your scans into searchable PDFs — the page image plus an invisible OCR text layer, so you can select, copy and Ctrl+F the text in any PDF viewer.
No daemons, no web servers: you run it in a terminal when you want to scan.
- Live TUI: page list with per-page status (scanning → cleaning → OCR →
ready), image preview (kitty/sixel when your terminal supports it,
halfblock fallback everywhere), extracted OCR text pane (
preview_ocr: on-demand per page, per capture, or off — the PDF's text layer is unaffected) - Multi-page by default: keep scanning while earlier pages clean in
the background — the scanner is free as soon as a capture ends, so you
never wait on the previous page; live per-page and session timers show
what's happening at all times; delete, reorder (
J/Kor←/→), rotate (R), and rescan individual pages before building - Searchable PDFs via OCRmyPDF/Tesseract, multiple languages (default: English + German); PDF/A output with automatic page-rotation fix
- Page cleanup: ocrmypdf
--deskew --cleanat finish (defaultcleanup = "off"); optional unpaper modes — a content-safe conservative passthrough, or the legacy filter stack (which can erase page edges on flatbed scans) - Diagnostics screen (
!) with install hints when something is missing — opens automatically if a preflight check fails; headless--doctorkept - Desktop notifications (optional), always-on log file for debugging
- Keyboard-first (vim keys and arrows), mouse support (click to focus, scroll panes)
- Rust 1.90+ (to build; a prebuilt binary just needs the tools below)
- Linux with SANE (
sane), HPLIP for HP devices (hplip) ocrmypdf,tesseract(+ language data),img2pdfpoppler-utilsforpdfunite(only needed when one session mixes DPIs)unpaper(optional; only for the unpaper cleanup modes)libnotifyfor notifications (optional)zenity,kdialogoryadfor the save dialog at finish (optional; without one — or when the tool can't open a window, e.g. over SSH — the finish confirm dialog just shows the default path)- A SANE-compatible scanner (USB-only models like the Deskjet 1050a work fine)
Build from source:
git clone https://github.com/j-stechmann/auto-scanner-ocr
cd auto-scanner-ocr
cargo build --releasePut the binary on your PATH (optional):
ln -s "$PWD/target/release/auto-scanner-ocr" ~/.local/bin/auto-scanner-ocrArch dependencies (note: ocrmypdf is in the AUR, not the official repos):
sudo pacman -S --needed sane hplip tesseract tesseract-data-eng tesseract-data-deu img2pdf poppler unpaper libnotify
yay -S ocrmypdf # AUR; alternative without an AUR helper: uv tool install ocrmypdfDebian/Ubuntu:
sudo apt install sane hplip ocrmypdf tesseract-ocr tesseract-ocr-eng tesseract-ocr-deu img2pdf poppler-utils unpaper libnotifyscanimage -L # should list your device
# if not:
sudo hp-setup -i # HP-specific setup, then try scanimage -L againauto-scanner-ocr # start the TUI
auto-scanner-ocr --doctor # check dependencies and scanner, then exit
auto-scanner-ocr --help # all optionsStartup is near-instant: the TUI paints in well under a second while the
scanner detection (scanimage -L, the slow part) and dependency checks run
in the background — the header shows detecting... and scanning unlocks
(s) the moment your device is found, typically within a few seconds.
Pressing s early buffers the scan intent; it fires automatically as soon
as the scanner is detected.
Inside the TUI:
| Key | Action |
|---|---|
s / Enter |
Scan next page (while the Pages pane is focused for Enter) |
Esc / c |
Cancel a running scan |
j/k or ↑/↓ |
Select page (Pages) · scroll (Text) |
J/K or ←/→ |
Move page down/up (Pages pane) |
r |
Rescan page with the current dpi/mode (keeps the old image until the new scan succeeds) |
R / < |
Rotate page 90° clockwise / counter-clockwise |
d |
Delete page (kills the job if it's still processing) |
1–9 |
Jump to page N |
f |
Build the searchable PDF (system save dialog: choose folder + filename) |
o |
Open the finished PDF with xdg-open |
n |
New session |
m |
Cycle scan mode: gray → color → lineart |
+/= / - |
DPI presets 150 / 200 / 300 / 600 |
L |
OCR language picker (lists installed tesseract data) |
Tab / click |
Cycle pane focus (Pages → Preview → Text) |
? / ! |
Help / diagnostics (press r inside to re-run checks) |
q / Ctrl-C |
Quit (confirm if pages aren't saved) |
Typical session: put page 1 on the glass, press s, wait for the scan, put
page 2 on the glass, press s again — the scanner is free as soon as page
1's capture ends (its text-pane OCR and cleanup continue in the background,
and under the default preview_ocr = "lazy" text is only extracted when
you view the page). Press f when done; the PDF lands in
~/Documents/scans/ as YYYY-MM-DD_HHMMSS.pdf by default — the system
save dialog (zenity/kdialog/yad when installed) opens first, so you can
pick another folder and/or filename; overwriting an existing file asks for
confirmation. Without a dialog tool, the confirm dialog shows the default
path instead. Cancelling the save dialog aborts the finish (press f
again to retry).
Small print: the default is 300 dpi — the OCR sweet spot, 2–3× faster
per capture and fine for normal 10–12pt text. For dense small print use
600 dpi (-d 600 or the + key). Higher than 600 is pointless on
flatbeds: 1200 dpi is interpolated and can stall cheap USB scanners
mid-pass.
| Flag | Meaning | Default |
|---|---|---|
-d, --dpi N |
scan resolution | 300 |
-M, --mode |
gray, color or lineart |
color |
-l, --langs A+B |
OCR languages, plus-separated | deu+Latin |
-o, --output DIR |
where PDFs are written | ~/Documents/scans |
-e, --device NAME |
SANE device name or substring | first found |
--no-unpaper |
alias for --cleanup off |
— |
--cleanup MODE |
page cleanup: off, conservative or legacy |
off |
--preview-ocr MODE |
text-pane OCR: eager (after capture), lazy (on demand) or off |
lazy |
--no-notify |
disable desktop notifications | — |
--config FILE |
use a specific config file | ./config.toml or ~/.config/auto-scanner-ocr/config.toml |
--doctor |
check dependencies and scanner, then exit | — |
-v, --verbose |
also print log output to the terminal | — |
Exit code: 0 on a healthy session and also when quitting while the
background scanner detection was still running (neutral); 1 only when the
machine was still unhealthy at quit time (failed checks or no scanner).
While no scanner is found, the app keeps re-checking in the background
(every few seconds) — plug one in and it is picked up automatically: the
error screen closes by itself and scanning unlocks. If a scanner arrives
later and everything is healthy, a normal quit still exits 0.
Defaults live in config.toml (keep it in the current working directory, or at
~/.config/auto-scanner-ocr/config.toml); every value can be overridden on
the command line. Same format as before:
[scan]
dpi = 300 # OCR sweet spot; 600 for dense small print
mode = "color" # gray | color | lineart
langs = "deu+Latin"
device = "auto"
output = "~/Documents/scans"
cleanup = "off" # off | conservative | legacy
preview_ocr = "lazy" # lazy (on demand) | eager (after capture) | off
unpaper_extra_args = [] # extra unpaper argv when cleanup != off
notify = trueAbout cleanup: the default off skips unpaper entirely — ocrmypdf's
--deskew --clean (which runs unpaper internally with conservative
settings) does the real work once at finish. unpaper's own default filter
stack (legacy) is tuned for book scans: on flatbed scans its mask/border
detection misfires and can erase page edges (measured: a whole table wiped).
conservative disables every content-altering filter (a verified pixel-identical
passthrough, kept as a hook for unpaper_extra_args). Old configs with
unpaper = true map to conservative (with a deprecation warning);
unpaper = false maps to off.
About preview_ocr: this controls only the per-page OCR that fills the
"Extracted text" pane in the TUI — the final PDF always gets its searchable
text layer from ocrmypdf at finish, whatever you pick here.
lazy (the default) extracts text only for the page you are currently
viewing, on demand: flipping pages never runs tesseract you didn't ask for,
and scans never wait on OCR. eager OCRs every page right after capture so
the pane is always filled. off skips the pane entirely (rotate then also
skips its re-OCR).
About langs: tesseract degrades when language models are mixed — German
umlauts turn into ligature confusions (für → fiir, Rück → Riick,
Grüßen → GruRen) when eng+deu is combined. For monolingual documents
stick to German plus the Latin script model (the default deu+Latin) or a
single language (deu, eng, …) and switch via the L picker or --langs
when you scan in another language. Measured on a real German letter: deu
alone and deu+Latin both produced zero broken umlauts; any eng mix
produced several.
About Latin: Latin is a tesseract script model, not a language —
it fixes the § → & artifact in German legal citations (& 115 SGB
instead of § 115 SGB) without hurting umlauts, at ~0.3s extra per page.
Debian/Ubuntu ship it (sudo apt install tesseract-ocr-script-latn); Arch
does not (its tesseract-data-lat is the Latin language model — a
different file that degrades umlauts in deu+lat mixes). On Arch, or when
your distro lacks the package, download the script model once — note that
tesseract's tessdata path varies (tesseract --list-langs -v shows where
your build looks):
curl -fsSL https://github.com/tesseract-ocr/tessdata_fast/raw/main/script/Latin.traineddata \
| sudo tee /usr/share/tessdata/Latin.traineddata >/dev/nullWithout it, deu alone misreads § as &/8&/$ regardless of scan
quality (verified up to 600 dpi) — it's a model limitation, not an input
problem. --doctor prints the install hint when Latin is configured but
missing.
The preview auto-detects the terminal's graphics protocol via a short-lived probe process: kitty graphics and sixel render native images; everywhere else it falls back to unicode halfblocks. The probe's first response must arrive within ~600 ms — local terminals answer in a few ms, but a very slow SSH link (or a heavily loaded tmux passthrough) can fall back to halfblocks, degrading only the image preview, never scanning. Inside tmux the probe queries raw (tmux swallows answers to its own passthrough-wrapped queries), so sixel works in tmux too when the outer terminal (e.g. foot) supports it. Detection never interferes with keyboard input — the probe runs in an isolated child process.
- Run
auto-scanner-ocr --doctor— it checks every dependency, tesseract language data, scanner detection and the output directory, and prints install hints for anything missing. Inside the TUI,!shows the same checks withrto re-run them. - The TUI runs the same checks at startup (in the background); if something
is missing you'll see the diagnostics screen automatically instead of a
mid-scan failure. The
rre-run inside diagnostics is non-blocking — the UI stays responsive while checks execute. A dismissed diagnostics screen is not re-opened for the same ongoing problem, but a new, different one (e.g. another tool disappears mid-session) pops it up again. - Wrong umlauts in the OCR text (
fiirinstead offür)? Yourlangsmixes two language models — pick the document's language alone withL(or setlangs = "deu"in the config). Mixed-language OCR reliably garbles umlauts; single-language OCR reads them correctly. §read as&,8&or$(& 115 SGBinstead of§ 115 SGB)? Thedeumodel alone misreads thin§glyphs as a model limitation — no scan setting fixes it (verified up to 600 dpi). Add theLatinscript model:langs = "deu+Latin"and install the data file (see "AboutLatin" above).- Logs are written to
~/.local/state/auto-scanner-ocr/auto-scanner-ocr.log; add-vto see them in the terminal. - Scanner not found? Check USB, power, and
scanimage -L. For HP devices runsudo hp-setup -ionce. - Quitting with un-built pages deletes them (the confirm dialog means it),
unless a PDF build was in flight — its session dir is then swept on the
next startup. Crash or signal leftovers under
~/.local/state/auto-scanner-ocr/sessions/are swept automatically on startup too: each session dir carries a lock file whose flock the kernel releases when the process dies, so dead owners are deleted immediately while a live instance's dir is never touched (even when suspended). This applies to instances of the same version; a session of the older (pre-lock) binary still running during an upgrade is not protected.
Each finish produces YYYY-MM-DD_HHMMSS.pdf in your output directory
(collision-safe _2 suffixes): a PDF/A document whose visible layer is your
scans (deskewed and cleaned) and whose invisible text layer contains the OCR
result — searchable and copy-pastable in any PDF viewer. Pages keep the
scanner window size of their own capture (mixed-DPI sessions are merged with
pdfunite). If ocrmypdf fails, the PDF is still saved (without a text
layer) and the TUI tells you so.
Development happens on the develop branch via git flow — see
CONTRIBUTING.md for branches, PRs and the release process.
GPL-2.0-or-later — see LICENSE. Changes are tracked in CHANGELOG.md.