Paperless-ngx: digitalizá todos tus documentos en casa con Linux

Paperless-ngx es un gestor de documentos open source que toma tus PDFs, los OCR-iza, los etiqueta automáticamente, los indexa para búsqueda full-text y los guarda donde tú quieras. Si te ahogás en facturas, recibos, contratos, garantías y papeles varios, Paperless-ngx los digitaliza una vez y te los hace accesibles desde cualquier dispositivo, sin que Google/Microsoft lean tus facturas médicas.

El problema del papel (y por qué digitalizar)

Todos acumulamos montañas de papel que no sabemos dónde están:

• Facturas de servicios (luz, gas, agua, internet)
• Recibos de compras (garantías, devoluciones)
• Contratos (alquiler, seguros, bancos)
• Documentos de identidad (DNI, pasaportes escaneados)
• Impuestos (declaraciones, recibos de sueldo)
• Manuales de electrodomésticos
• Cartas, documentos legales, certificados

El paper tradicional se pierde, se deteriora, y ocupa espacio. Pero escanear y guardar PDFs sin más es peor: terminás con 2000 PDFs anónimos en una carpeta, imposibles de buscar.

Paperless-ngx resuelve esto: cada documento que entra se procesa automáticamente, se le asignan tags, se detecta de qué tipo es (factura, recibo, contrato), y queda buscable por texto completo.

¿Qué es Paperless-ngx exactamente?

Paperless-ngx es un fork mantenido y activo del Paperless original (que está prácticamente abandonado desde 2020). Escrito en Python + Django, corre en Docker o como servicio Linux. Tiene:

• OCR automático con Tesseract (gratis, soporta 100+ idiomas incluyendo español)
• Web UI moderna para browsear, buscar y editar metadata
• API REST completa
• Consume folder: carpeta donde tirás cosas (PDFs, imágenes, emails) y las procesa automáticamente
• Tags y tipos de documento configurables
• Correspondientes (de quién es el documento: empresa, persona)
• Búsqueda full-text ultra rápida con PostgreSQL
• Workflows (reglas automáticas basadas en regex, contenido, etc.)
• Integración con scanners via SANE
• Share links con expiración para compartir docs puntuales

La versión actual (2026) tiene ~80 contributors activos, releases frecuentes, y es el estándar de facto.

Instalación con Docker (la más simple)

Requisitos

• Docker + Docker Compose
• 2 GB RAM mínimo (recomendado 4 GB para OCR rápido)
• 20 GB disco para empezar (crece con el tiempo)

docker-compose.yml

version: "3.8"
services:
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    restart: unless-stopped
    depends_on:
      - broker
      - db
    ports:
      - "8000:8000"
    volumes:
      - /srv/paperless/data:/usr/src/paperless/data
      - /srv/paperless/media:/usr/src/paperless/media
      - /srv/paperless/export:/usr/src/paperless/export
      - /srv/paperless/consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: changeme
      PAPERLESS_SECRET_KEY: $(openssl rand -hex 32)
      PAPERLESS_URL: https://docs.tudominio.com
      PAPERLESS_OCR_LANGUAGE: spa+eng
      PAPERLESS_TIME_ZONE: America/Argentina/Buenos_Aires
  db:
    image: postgres:16
    container_name: paperless-db
    restart: unless-stopped
    volumes:
      - /srv/paperless/db:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: changeme
  broker:
    image: redis:7
    container_name: paperless-redis
    restart: unless-stopped

Levantar:

Este bloque crea la estructura de directorios que docker-compose espera y levanta los servicios en segundo plano. Usar logs -f paperless en el primer arranque es la forma más rápida de detectar errores de configuración antes de seguir con la UI.

mkdir -p /srv/paperless/{data,media,export,consume,db} con brace expansion crea los 5 directorios de un solo comando (data para SQLite/index, media para los archivos originales, export para descargas, consume para el drop folder, db para el volumen de PostgreSQL). docker compose up -d (con -d = detached) lee el docker-compose.yml del directorio actual, levanta paperless, paperless-db y paperless-redis en background y devuelve control. docker compose logs -f paperless queda viendo los logs hasta que presiones Ctrl+C — usalo mientras esperas a que termine el migrate inicial.

mkdir -p /srv/paperless/{data,media,export,consume,db}
docker compose up -d
docker compose logs -f paperless  # ver el primer arranque

Troubleshooting: Si los volúmenes no existen o no son escribibles, el servicio falla al primer migrate; asegurate de que el usuario del contenedor pueda escribir y que openssl rand -hex 32 no haya devuelto una cadena vacía. verifica que paperless, paperless-db y paperless-redis estén Up y que el log no muestre connection refused a la base de datos.

Acceder a http://localhost:8000. Crear superuser:

Este comando crea el superusuario inicial desde el contenedor y completa la primera configuración. Sin ese paso, la web UI rechaza el login aunque el servicio esté corriendo.

docker exec -it paperless abre una shell interactiva dentro del contenedor paperless (el -i mantiene STDIN abierto, -t asigna un pseudo-TTY para prompts interactivos). python manage.py createsuperuser es el comando Django estándar que Paperless hereda; te va a pedir username, email y password uno por uno. Conviene correrlo después de que docker compose logs -f paperless muestre que el migrate inicial terminó sin errores, sino falla con relation "auth_user" does not exist.

docker exec -it paperless python manage.py createsuperuser

Troubleshooting: Si la terminal no es interactiva, agregá -it; si la base de datos no terminó de migrar, vas a recibir un error de conexión. verifica que puedas iniciar sesión en http://localhost:8000 con esas credenciales antes de seguir con la configuración.

Listo. Paperless-ngx está corriendo.

Configuración inicial esencial

Una vez dentro, hay que configurar varias cosas que hacen la diferencia entre “un repositorio de PDFs” y un sistema útil.

1. Cambiar el idioma del OCR

Settings → OCR → Language. Para español de Latinoamérica: spa. Para multi-idioma: spa+eng o spa+eng+fra+por+deu.

Si escaneás documentos viejos con tipografías raras o manuscritos, prueba spa+eng siempre.

2. Configurar el “consume folder”

Es la carpeta /srv/paperless/consume. Cualquier cosa que pongas ahí (PDF, JPG, PNG, TIFF, email) se procesa automáticamente:

1. OCR

2. Detección de tipo de documento

3. Asignación automática de tags y corresponding

4. Mover a /srv/paperless/media

Workflow típico:

• Escaneás factura → guardas en consume (con app mobile, script, scanner)
• A los 5 segundos Paperless la procesó
• Aparece en la UI con su tag, OCR, y buscable

3. Crear tags y tipos

Settings → Tags. Creá tags como:

• factura-luz
• factura-gas
• recibo-sueldo
• contrato
• garantia
• impuesto
• banco
• salud

Settings → Document Types. Tipos como:

• Factura
• Recibo
• Contrato
• Identificación
• Manual

4. Configurar correspondentes

Correspondiente es “de quién viene” el documento. Paperless detecta automáticamente algunos via regex.

Settings → Correspondents. Agregar manualmente:

• Empresa de Luz SA
• Banco X
• Hospital Y

5. Crear reglas de auto-tagging

Settings → Workflows. Las reglas aplican tags automáticamente según el contenido:

# Workflow ejemplo: facturas de luz
name: "Tag factura EDESUR"
match: "all"
rules:
  - name: "contiene 'EDESUR'"
    type: "content"
    value: "EDESUR"
  - name: "es PDF"
    type: "document_type"
    value: "application/pdf"
actions:
  - type: "assign_tag"
    value: "factura-luz"
  - type: "assign_correspondent"
    value: "EDESUR"

Una vez configuradas las reglas, cada documento nuevo se etiqueta solo.

OCR: la magia técnica

Tesseract es el motor OCR open source mantenido por Google. Paperless-ngx lo usa via ocrmypdf para PDFs escaneados.

Mejorar la calidad del OCR

Resolución: escaneá a 300 DPI mínimo (600 para documentos deteriorados o manuscritos).

Pre-procesamiento: si escaneás muchas cosas, configura PAPERLESS_OCR_IMAGE_DPI=300 o más en el env.

Idiomas múltiples: para documentos que mezclen idiomas (ej: contrato en español pero con encabezado en inglés), usa spa+eng.

PDFs nativos vs escaneados: si el PDF ya tiene texto embebido (es un PDF generado, no escaneado), Paperless usa el texto directo y solo hace OCR si no lo encuentra. Esto es instantáneo vs minutos para OCR real.

Hardware para OCR rápido

Por defecto, OCR corre en CPU. Si tienes servidor con buena CPU, va decente. Si tienes muchos documentos para procesar, puedes:

• Usar ocrmypdf con GPU (experimental, no siempre vale la pena)
• Distribuir el trabajo con Celery en varias workers
• Procesar en background (ya lo hace por default con Redis)

Para un usuario normal con ~50 docs/mes, el OCR default está perfecto.

Integración con scanner

Si tienes un scanner físico (Brother, Canon, Epson), hay varias formas de Paperless-ngx lo absorba automáticamente:

Método 1: SANE + scan script

Este script instala SANE, escanea a TIFF, le aplica OCR a español/inglés y deja el PDF en el consume folder para que Paperless lo absorba. La cadena es deliberada: scanimage produce un TIFF crudo, tesseract lo entiende bien y el PDF resultante se nombra desde el propio OCR.

sane-utils provee scanimage, el CLI de SANE para controlar scanners compatibles. --resolution 300 es el mínimo razonable para OCR (debajo de eso, Tesseract pierde precisión en tipografías chicas); arriba de 600 DPI el archivo pesa mucho y la mejora es marginal. --format=tiff produce un TIFF sin compresión con pérdida, formato nativo para OCR. tesseract ... -l spa+eng pdf corre OCR multi-idioma sobre el TIFF y devuelve un PDF con capa de texto seleccionable (lo que distingue un PDF buscable de uno que es pura imagen). El cp final mueve el PDF al consume folder.

# Instalar SANE
sudo apt install sane-utils
# Escanear a PDF directo al consume folder
scanimage --resolution 300 --format=tiff > /tmp/scan.tiff
tesseract /tmp/scan.tiff /tmp/scan-ocr -l spa+eng pdf
cp /tmp/scan-ocr.pdf /srv/paperless/consume/

Troubleshooting: Si scanimage no detecta el equipo, revisa que el usuario pertenezca a saned o al grupo del backend; si Tesseract se demora o falla, comprobá el idioma con tesseract --list-langs. verifica que el PDF final abra con texto seleccionable, no como imagen escaneada; si es imagen, el OCR no corrió o se cortó por falta de memoria.

Método 2: Paperless consume via SMTP (email)

configura Paperless para tener una dirección de email. Cualquier cosa que mandes a esa dirección se procesa igual.

Settings → Email:

• IMAP server: imap.gmail.com
• Username: [email protected]
• Password: app password de Gmail
• Folder: INBOX

Ahora reenviar un email con un PDF adjunto a [email protected] lo incorpora.

Método 3: App mobile

Paperless Mobile (Android/iOS) te permite:

• Escanear con la cámara del teléfono (auto-crop, perspectiva, enhancement)
• Subir archivos existentes
• Buscar y ver documentos
• Agregar tags manualmente

Es la forma más cómoda para documentos puntuales. Open source, sin tracking.

Método 4: Scanner directo (algunos modelos)

Scanners Brother y Epson modernos soportan “scan to FTP” o “scan to SMB”. configuras el destino a /srv/paperless/consume/ y listo, cada scan se procesa solo.

Búsqueda full-text

Una vez que tienes 500+ documentos, la búsqueda es tu mejor amiga.

Desde la web UI

El campo de búsqueda arriba a la derecha busca en:

• Título
• Contenido (lo que extrajo el OCR)
• Tags
• Correspondent
• Tipo

Ejemplos:

• "factura 2024" → facturas del 2024
• "AFIP" → cualquier documento que mencione AFIP
• tag:garantia AND type:factura → syntax de búsqueda avanzada

Búsqueda booleana

Soporta AND, OR, NOT:

• luz OR gas → cualquiera de los dos
• "EDESUR" -recibo → menciones EDESUR pero no recibos
• created:[2024-01-01 TO 2024-12-31] → rango de fechas

API

Esta consulta usa la API REST para validar que el sistema de búsqueda indexó y responde. Hacerlo al inicio te permite saber que el endpoint responde y que la consulta AFIP encuentra resultados antes de integrarlo con un script o una automatización.

La API de Paperless-ngx usa token authentication en el header Authorization: Token , no Bearer. El token se genera desde la web UI (My Profile → API Token). curl con -H agrega el header de auth; los filtros se pasan como query string (?query=AFIP, ?tags__id=5, ?created__date__gte=2024-01-01). La respuesta es JSON paginado con count, next, previous y results. Para iterar todos los documentos usa ?page=N o un script con next links.

# Buscar vía API
curl -H "Authorization: Token ***" 
  "http://localhost:8000/api/documents/?query=AFIP"

Troubleshooting: Si devuelve 401, el token no es válido o se revocó; si la lista está vacía, el OCR puede no haber indexado aún o el campo de búsqueda es distinto. verifica la paginación y los filtros antes de tomar la respuesta vacía como ausencia de datos.

Compartir documentos de forma segura

Paperless-ngx permite generar links temporales para compartir un documento sin dar acceso a todo el sistema:

1. Abrí el documento

2. Click “Share Link”

3. configura: expiración (1 día, 1 semana), máximo de veces que se puede abrir

4. Compartí el link

El receptor ve el PDF en una página simple, no necesita cuenta, y el link expira solo.

Útil para:

• Mandar una factura al contador
• Compartir un contrato con un abogado
• Enviar un manual a un familiar

Organización: el workflow que funciona

Después de probar varios esquemas, el que mejor funciona a largo plazo es:

1. Tag por categoría de vida

• hogar (facturas, contratos del hogar)
• salud (estudios médicos, recetas, facturas de prepaga)
• trabajo (recibos de sueldo, contratos laborales)
• vehiculos (seguro, VTV, patente)
• impuestos (declaraciones, comprobantes)
• garantias (todo lo que tenga garantía)

2. Tag por tipo

• factura
• recibo
• contrato
• manual
• identificacion

3. Tag temporal si aplica

• vencimiento-2026-Q3
• recordatorio-anual

4. Workflows automáticos

Una vez que tienes 10+ tags, configura workflows para asignarlos solos. La regla: cuanto más automático, menos curas manualmente.

5. Revisión semanal

Poné un recordatorio: “Lunes 9 AM, revisar documentos nuevos”. 10 minutos para clasificar lo que el OCR no pudo. Con el tiempo, cada vez menos.

Backup y restore

Paperless guarda todo en /srv/paperless/data y /srv/paperless/media. Backup:

Este script consolidado de backup arma un dump de PostgreSQL, archiva config y media y rota los archivos más viejos a 90 días. Tener todo en /srv/backups/paperless permite restaurar en otro host siguiendo los pasos en orden inverso.

El flujo es: pg_dump desde el contenedor de la DB (con -U paperless y nombre de DB) produce un dump SQL que se comprime con gzip (los dumps de Postgres son altamente comprimibles, típicamente 5-10x). tar -czf archiva los directorios data (SQLite, índice, config) y media (los PDFs originales) en un solo archivo. find ... -mtime +90 -delete purga backups con más de 90 días de antigüedad. Para restaurar, invertí el orden: primero el tar, después el pg_restore (o psql si usaste el formato plain SQL).

#!/bin/bash
# /usr/local/bin/paperless-backup.sh
BACKUP_DIR=/srv/backups/paperless
DATE=$(date +%Y%m%d)
mkdir -p $BACKUP_DIR
# DB
docker exec paperless-db pg_dump -U paperless paperless | gzip > $BACKUP_DIR/db-$DATE.sql.gz
# Config y media
tar -czf $BACKUP_DIR/files-$DATE.tar.gz 
  /srv/paperless/data 
  /srv/paperless/media
# Limpiar backups >90 días
find $BACKUP_DIR -type f -mtime +90 -delete

Troubleshooting: Si pg_dump falla, asegurate de que la base de datos esté arriba y que las credenciales del contenedor coincidan; si tar se queja de archivos cambiando, reintentá con --warning=no-file-changed. verifica que los .sql.gz y .tar.gz estén completos con un test de integridad antes de dar el backup por bueno.

Restaurar es lo inverso. Importante: hacer backup ANTES de cada update de Paperless (los releases a veces cambian schema y hay que migrar DB).

Cuándo NO usar Paperless-ngx

• No tienes scanner ni smartphone: sin digitalizar documentos, no hay material.
• <20 documentos por año: si solo te guardas 5 cosas al año, un Nextcloud con carpeta es suficiente.
• necesitas búsqueda semántica o AI: Paperless-ngx es búsqueda por keywords, no entiende significado. Para eso hay que sumarle OCR + embeddings + vector store (proyecto separado).
• Tu sistema legal requiere firma digital certificada: Paperless guarda PDFs simples, no firmas avanzadas.

Preguntas frecuentes

Lee también

• Guía Fedora 44: Novedades, Instalación y Upgrade para Sysadmins Linux
• Configura VLANs en Linux con nmcli: Guía paso a paso para sysadmins
• Protege tu SSH: Guía esencial para configurar Fail2ban en Linux
• Guía Definitiva: Configura Kubernetes con kubeadm en Ubuntu para Sysadmins Linux
• Configura Prometheus y Grafana: Guía DevOps para SysAdmins Linux