Paperless Scanner

Scan documents and upload to Paperless-ngx in one seamless workflow.

Cross‑platform (SOON) GUI GPLv3

Overview

A desktop application that streamlines the process of scanning documents and uploading them to Paperless‑ngx. Tired of scanning, logging in, uploading, and cleaning up? This app does it all in one workflow.

Before diagram
Before
After diagram
After

One‑Click Scanning

Scan documents directly with a simple button click.

AI Filenames

Smart suggestions using OpenAI or Google Gemini.

Paperless‑ngx Upload

Send documents with proper metadata in seconds.

Auto Scanner Detection

Find and manage available scanners automatically.

App screenshot

Installation

Prerequisites

  • Python 3.10 or higher
  • Windows, macOS, or Linux with a compatible scanner
  • Running Paperless‑ngx instance
  • Optional: OpenAI API key or Google Gemini API key

Paperless API Token

  1. Log into your Paperless‑ngx instance
  2. Go to Settings → Users → Your User → API Tokens
  3. Create a token with appropriate permissions

Configure

Settings screenshot
Settings
Config screenshot
Config

Usage

Run from source

python app.py
  1. Select your scanner (if multiple are available)
  2. Click "Scan Document"
  3. Enter a filename or accept the AI suggestion
  4. Click "Save" to save locally
  5. Click "Upload to Paperless"

Build a standalone app

For macOS packaging via py2app:

python setup.py py2app

Generic build (e.g., Windows/Linux) via PyInstaller:

pyinstaller app.py -n paperless-scanner --icon icon.ico

Configuration

Paperless‑ngx

  • api_url: your instance URL (http/https)
  • api_token: API token (Profile → API Auth Token)

AI (optional)

  • openai_api_key or
  • gemini_api_key

Supported Scanners

Designed to work with most scanners supported by your OS. Tested devices include:

Brother

  • DS940DW
  • DS640
  • RDS740D

Epson

  • ES50

HP

  • HPPS200

Troubleshooting

Scanner not detected

  • Ensure your scanner is connected and powered
  • Verify drivers are installed (WIA/SANE/ICA as applicable)
  • Refresh the scanner list

Upload fails

  • Verify Paperless‑ngx URL and API token
  • Ensure the instance is reachable
  • Confirm token permissions

AI suggestions not working

  • Check your OpenAI or Gemini API key
  • Confirm connectivity and credits
  • Try switching providers

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make changes
  4. Run tests
  5. Open a pull request

License

Released under GPL v3. See License.md for the full text.