Skip to content
AimarmndzPublic

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

scan2nas

🌐 English · Español

release platform GUI CLI license

Preset-based document scanning for Epson scanners on Linux — scan an ID card, a passport photo or a full multi-page booklet with one command (or one click), and get a correctly sized PDF saved straight into any folder, including a network share on your NAS.

Born out of a real-world itch: Epson's official "scan to computer" button and mobile-app conveniences don't exist on Linux, and scanning small documents on a flatbed always produces a huge, mostly blank A4 PDF. scan2nas fixes both.

Scan view

More screenshots

Settings view

Features

  • Size presets — the scan area matches the document, so an ID card comes out as an ID-card-sized PDF, not a blank A4 page with a card in the corner. Ships with presets for ID/bank cards (ISO ID-1), A4, A5, Letter, 10×15 cm photos, passport photos (Spain 26×32, EU/UK 35×45, US 2×2″) and the Spanish Libro de Familia (single page and opened), plus a full-glass mode.
  • Custom presets — add your own sizes in the config file with one line.
  • Multi-page PDFs — scan page after page and get a single merged PDF.
  • Desktop app with live preview — a Qt (PySide6) application: pick a preset, scan, review each page before anything is saved, remove or re-scan pages, browse your scan history, and tweak settings — all in one window.
  • Printing too — send any PDF to your printer from the desktop app (printer picker, copies, colour/monochrome, fit-to-page), or reprint a scan straight from the history. Uses CUPS underneath.
  • Also a CLI — a persistent kdialog menu when launched without a terminal; plain arguments when run from a terminal or a script.
  • Scan to anywhere — the output folder is just a path: local, USB, or a mounted NAS share (see Saving to a NAS).
  • Bilingual — English and Spanish interface, picked from your locale.
  • Sane defaults — 24-bit colour, 300 dpi, timestamped file names, no overwriting.

Requirements

Dependency Arch package Debian/Ubuntu package Purpose
epsonscan2 epsonscan2 (AUR, bundles network plugin) epsonscan2 + non-free plugin (Epson downloads) drives the scanner
python3 python python3 builds per-job scan settings
pdfunite, pdftoppm poppler poppler-utils merge / render PDFs
magick imagemagick imagemagick rotate sideways scans
kdialog, notify-send kdialog, libnotify kdialog, libnotify-bin CLI menu mode only
PySide6 (Qt 6 + QtPdf) pyside6 python3-pyside6.qtpdfwidgets desktop app only
lp, lpstat cups cups-client printing only

Any scanner supported by epsonscan2 should work. Developed and tested with an Epson EcoTank ET-2865 (ET-2860 series) over Wi-Fi.

Installation

Supported distributions: Arch Linux (and derivatives: CachyOS, Manjaro, EndeavourOS…), Debian 12+ and Ubuntu 22.04+. The moving pieces are the same everywhere; what changes per distro is how Epson's driver and PySide6 are obtained — both covered below.

Quick start (all distros)

git clone https://github.com/Aimarmndz/scan2nas.git
cd scan2nas
./install.sh      # per-user install: ~/.local/bin + app launcher, no root
scan2nas --init   # guided setup: dependencies, services, NAS, printer, scanner

scan2nas --init is the guided first-time setup (uses sudo where needed):

  1. Installs missing dependencies with your distro's package manager (pacman on Arch — including epsonscan2 from the AUR via paru/yay — or apt on Debian/Ubuntu, pointing you to Epson's download for the driver, which is not in Debian's repositories).
  2. Enables the CUPS printing service (and Avahi for network discovery).
  3. Optionally mounts a NAS share over SMB: asks server, share, user and password, stores credentials in a root-only file (/etc/cifs-creds-scan2nas), adds a systemd automount entry to /etc/fstab and verifies the mount before using it.
  4. Adds your network printer as a driverless (IPP Everywhere) CUPS queue if none exists yet.
  5. Discovers the scanner and writes the initial configuration.

It is safe to re-run at any time. If you prefer to control every step yourself, follow your distro's section below and finish with the no-sudo scan2nas --setup (scanner + folder only).

Arch Linux (CachyOS, Manjaro, EndeavourOS…)

Everything is packaged. With an AUR helper (paru or yay):

sudo pacman -S --needed python poppler imagemagick cups cifs-utils \
                        kdialog libnotify pyside6
paru -S epsonscan2                       # AUR; bundles the network plugin
sudo systemctl enable --now cups.service avahi-daemon.service

Notes:

  • The AUR epsonscan2 package compiles Epson's source and already includes the non-free network plugin — nothing else to download.
  • pyside6 (official repos) provides Qt 6 with the QtPdf module used by the desktop app.

Debian 12 (Bookworm) and newer

sudo apt update
sudo apt install python3 poppler-utils imagemagick cups cups-client \
                 cifs-utils kdialog libnotify-bin \
                 python3-pyside6.qtpdfwidgets python3-pyside6.qtpdf
sudo systemctl enable --now cups avahi-daemon

Epson's driver is not in Debian's repositories. Download the epsonscan2 bundle for your architecture (x86_64/deb) from Epson's download centre — the bundle tarball includes the core driver and the non-free plugin required for network scanning — then:

tar xzf epsonscan2-bundle-*.x86_64.deb.tar.gz
cd epsonscan2-bundle-*
sudo ./install.sh        # Epson's installer: core + ocr + network plugins

Verify with epsonscan2 --list (the scanner must be on and on the same network).

Ubuntu 22.04 LTS and newer

Same as Debian — all packages live in the universe repository, so enable it first if you haven't:

sudo add-apt-repository universe
sudo apt update
sudo apt install python3 poppler-utils imagemagick cups cups-client \
                 cifs-utils kdialog libnotify-bin \
                 python3-pyside6.qtpdfwidgets python3-pyside6.qtpdf
sudo systemctl enable --now cups avahi-daemon

Then install Epson's driver bundle exactly as in the Debian section above.

Prefer a package? Every release ships a scan2nas_<version>_all.deb — install it with sudo apt install ./scan2nas_*_all.deb (it pulls the right dependencies) and you can skip git clone + install.sh entirely. You still need Epson's driver bundle. For Arch there is a PKGBUILD under packaging/aur/.

On Ubuntu 22.04 the python3-pyside6.* packages are older but sufficient; if they are missing on your flavour, pipx install scan2nas-gui from the repo root installs the GUI with its own PySide6.

Verify the installation

epsonscan2 --list        # should print your scanner's IP / model ID
lpstat -e                # should list at least one printer queue
scan2nas --list-presets  # should print the preset table

Configuration file

Settings live in ~/.config/scan2nas/config and are shared by the CLI and the desktop app:

SCANNER_IP=192.168.1.50
OUTPUT_DIR="/mnt/nas/scans"
RESOLUTION=300
MARGIN_MM=4
DEFAULT_COLOR=color

Updating and uninstalling

git pull && ./install.sh   # update
./install.sh --uninstall   # remove (keeps ~/.config/scan2nas)

Usage

Desktop app

Launch scan2nas from the applications menu, or run scan2nas-gui. Pick a document format, colour mode and resolution, press Escanear, and review the result before it is saved anywhere:

  • Every scanned page appears in the preview with a thumbnail strip; add more pages, remove a bad one, or discard the whole job.
  • Guardar merges all pages into one timestamped PDF in your output folder.
  • Historial lists the latest PDFs in the output folder with a built-in viewer; Ajustes edits the scanner IP, output folder, resolution and margin.

The app shares its configuration with the CLI (~/.config/scan2nas/config).

The Imprimir view sends any PDF on disk to a CUPS printer: pick the file (or hit Imprimir on a scan in the history), choose printer, copies, colour or monochrome and fit-to-page, and print. Your CUPS default printer is preselected.

CLI menu

Run the CLI without a terminal (e.g. from a custom launcher) to get a persistent kdialog menu: pick what you are scanning, choose single or multi-page, and the scanner runs. The menu comes back after every job; press Cancel to quit. Desktop notifications report every saved file.

From a terminal

scan2nas idcard                 # scan an ID card
scan2nas a4                     # scan an A4 document
scan2nas passport-eu            # scan an EU/UK passport photo
scan2nas family-book multi      # scan several pages into ONE merged PDF
scan2nas --list-presets         # see everything available

In multi-page mode you are prompted after each page: press Enter to scan the next one, n to finish and merge.

Files are saved as scan-<preset>-<date>-<time>.pdf in your output folder.

Presets

Preset Size (mm) Notes
idcard 85.6 × 53.98 ISO/IEC 7810 ID-1 — national IDs, bank cards
a4 210 × 297
a5 148 × 210
letter 215.9 × 279.4
photo 100 × 150 standard photo print
passport-es 26 × 32 Spanish passport photo
passport-eu 35 × 45 EU / UK passport photo
passport-us 51 × 51 US passport photo (2 × 2 in)
family-book 118 × 165 Spanish Libro de Familia, one page
family-book-open 165 × 236 opened booklet, place it sideways; auto-rotated
full 215.9 × 297 whole glass

Spanish aliases work too: dni, tarjeta, carta, foto, pasaporte, pasaporteue, pasaporteusa, libro, librodoble, completo, and varias for multi.

Custom presets

Add a line to ~/.config/scan2nas/config:

PRESET_receipt="80x200"           # width x height in mm
PRESET_ledger="200x280 rotate"    # "rotate" = scanned sideways, auto-rotated

Then run scan2nas receipt — it also appears in the GUI menu.

Placing documents

Place the document against the corner of the glass marked with the arrow. Every preset includes a small margin (MARGIN_MM, default 4 mm) so exact placement is not critical. Note that flatbed scanners cannot capture the last 1–2 mm right at the glass edge.

Saving to a NAS

scan2nas writes to whatever OUTPUT_DIR points at. To make that a NAS share, mount it with automount so it reconnects on every boot. Example for a SMB/CIFS share, in /etc/fstab:

//nas.local/scans  /mnt/nas/scans  cifs  credentials=/etc/cifs-creds,uid=1000,gid=1000,iocharset=utf8,noauto,x-systemd.automount,x-systemd.idle-timeout=60,_netdev  0  0

with /etc/cifs-creds (readable only by root, chmod 600):

username=youruser
password=yourpassword

Then set OUTPUT_DIR="/mnt/nas/scans" — done. NFS works the same way with an nfs fstab entry.

Troubleshooting

  • Scans come out blank / all white — the settings template generated by epsonscan2 defaults to 1-bit black & white with a zero threshold on some versions. scan2nas forces 24-bit colour on every job precisely to avoid this; if you edited the template, re-run scan2nas --setup.
  • Scanner not found — check it is on and on the same network: epsonscan2 --list. If its IP changed, edit SCANNER_IP in the config (giving the scanner a static IP/DHCP reservation in your router avoids this). For USB scanners, set SCANNER_IP= empty and pass no IP.
  • "Cannot write to ..." — the output folder is missing or the network share is not mounted. Check ls <OUTPUT_DIR> and your fstab entry.
  • family-book-open pages come out upside down — place the booklet rotated the other way, or change -rotate 90 to -rotate -90 in the straighten function.
  • Left/top edge of the document is cut — flatbeds have a small dead zone at the very edge of the glass; move the document a couple of millimetres away from the corner (the preset margin absorbs the offset).

How it works

epsonscan2 (Epson's official Linux driver) has a little-known CLI mode driven by an .SF2 settings file (JSON). scan2nas keeps a template generated by epsonscan2 --create and, for every job, patches it with the preset's scan area (mm → pixels at the configured dpi, clamped to the glass), colour mode, resolution and a temporary output folder — then runs epsonscan2 --scan, post-processes if needed (rotation via poppler + ImageMagick), merges pages with pdfunite, and moves the final timestamped PDF into your output folder.

Contributing

Issues and pull requests are welcome — see the contributing guide for project layout, conventions and the testing checklist, and the roadmap for ideas looking for an owner. This project follows the Contributor Covenant code of conduct; security issues go through private reporting.

License

MIT

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages