Skip to main content
suchi import paperless consumes a standard document_exporter output bundle (with or without --split-manifest). Migration is one command and is idempotent — safe to re-run against a nightly export during a shadow window.

​
Prerequisites

  • A completed export bundle at /path/to/export. If you don’t have one, run this on the source side:
  • A running suchi instance with at least one user (usually the admin from /setup).
  • Enough free disk for the CAS to absorb every unique document blob (originals + optional archive PDFs).

​
The one-liner

The importer:
  1. Loads every manifest object (top-level manifest.json plus any per-document sidecar files under <root>/ or <root>/documents/).
  2. Upserts tags, correspondents, document types, storage paths, and custom-field definitions verbatim. Names are the identity — re-running against a modified export updates the row.
  3. For each document, streams the original (and optional archive) file into the CAS by SHA-256, then inserts one documents row plus tag junctions and custom-field values in a single transaction. paperless_id_legacy is preserved for round-tripping and dedup.

​
Dedup

Documents are keyed by the SHA-256 of the ingested bytes and by paperless_id_legacy. A re-run against the same bundle skips every already-imported document — the counter is reported as Skipped (dupes). Idempotent by construction.

​
Category resolution

By default, every imported document lands in the JD inbox — visible, bulk-reassignable, never lost. Three flags override:
Force every doc to the inbox. Never consult a rule. Use this if you want your existing tag/correspondent workflow untouched — the inbox is your one bucket, JD affordances stay hidden in the UI.
The three flags are mutually exclusive — pick one strategy.

​
Verify (dry-diff)

The shadow-window primitive: diff a nightly export against the live suchi DB without writing.
Report partitions every document in the bundle into:
  • New — would be imported (no matching paperless_id_legacy).
  • Match — present locally + compared fields all agree.
  • Differ — present locally, but at least one compared field diverges. The report lists the field names.
  • Orphan — present in suchi with a paperless_id_legacy that isn’t in this bundle. Suggests a source-side deletion since the last export.
Compared fields (Phase 1): title, original_size. Deliberately minimal — OCR text drifts trivially across source versions and would false-positive.

​
Shadow migration recipe

The recommended cutover for cautious operators:
1

Stand suchi up alongside the source system

Point it at the same backup pipeline.
2

Every night, verify

Run document_exporter on the source side and suchi import paperless --verify on the suchi side.
3

Watch the diffs settle

Any long-standing Differ or Orphan entries are the real migration surface to investigate.
4

Cut over

When diffs are boring, do a full --auto-jd (or --map-jd) import.
5

Repoint clients

Update mobile apps and staging-dir producers to point at suchi.
6

Cool off

Keep the source running for a two-week cool-off, then decommission.
The maintainer’s own instance follows this recipe (Phase 8).