Importing a Paperless-ngx export

​

Prerequisites

• A completed export bundle at /path/to/export produced by document_exporter (or an equivalent that emits the same manifest.json + originals/ + archive/ + json/ tree).
• 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).

​

Getting the dump out of paperless-ngx

docker compose exec webserver \
    document_exporter -p -sm /usr/src/paperless/export

sudo -u paperless python manage.py \
    document_exporter -p -sm /path/to/export

• -p — folder-prefixed layout. Produces originals/, archive/, thumbnails/, json/ under the export root instead of a flat dump.
• -sm — split manifest. Writes one JSON sidecar per document under json/ instead of one huge manifest.json. Suchi reads either shape, but the split form is faster on large corpora and lets the export resume incrementally.

docker cp \
    "$(docker compose ps -q webserver):/usr/src/paperless/export" \
    ./paperless-export

paperless-export/
  manifest.json    # workflows, saved views, users, groups, custom fields
  json/            # per-document sidecars (present when -sm was used)
  originals/       # source files
  archive/         # OCR'd PDFs (when paperless has produced them)
  thumbnails/      # optional, ignored by suchi

• Version. Suchi’s importer targets paperless-ngx v3.0.5 (see Migration target version). Newer minor versions are not a supported compatibility surface — the report will flag unknown shapes as Failed with reason “paperless version drift” so you can decide what to do.
• Duration. document_exporter reads every original + every archive PDF end-to-end. On corpora over a few thousand docs, run it during a maintenance window; the exporter is safe to interrupt and re-run.

​

Review, then import

suchi import --from /path/to/export --dry-run

suchi import --from /path/to/export \
  --owner-email [email protected] \
  --report ./import-report.md

​

Docker Compose

export EXPORT_DIR=/absolute/path/to/paperless-export

docker compose run --rm --no-deps \
  -v "$EXPORT_DIR:/imports/paperless:ro" \
  suchi import --from /imports/paperless --dry-run

docker compose run --rm --no-deps \
  -v "$EXPORT_DIR:/imports/paperless:ro" \
  suchi import --from /imports/paperless \
    --owner-email [email protected] \
    --report /data/import-report.md

docker compose exec suchi cat /data/import-report.md

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 within the selected system. Names are local identities — re-running there against a modified export updates that system’s row only.
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. legacy_id is preserved for round-tripping and dedup.

​

Dedup

​

Category resolution

suchi import --from ./export --owner-email [email protected] --flat

[[rules]]
if = "tag:tax"
category = 22

[[rules]]
if = "storage_path:Insurance"
category = 23

[[rules]]
if = "document_type:Utility"
category = 31

[[rules]]
if = "correspondent:Landlord"
category = 32

suchi import --from ./export --owner-email [email protected] \
    --map-jd mapping.toml

suchi import --from ./export --owner-email [email protected] --auto-jd

​

Migration target version

​

Workflows → automations

​

Saved views

​

JD categorization

• --flat sends every imported document to the inbox.
• --map-jd <file> applies the first matching HuML or TOML rule.
• --auto-jd uses the bundled deterministic keyword mapping.

​

Migration report

• Header — timestamp, source bundle root, target datadir, duration, active JD strategy.
• Summary — rows per model class (Documents / Tags / Correspondents / Document types / Storage paths / Custom fields / Notes / Workflows / Saved views), columns Full / Partial / Failed.
• Partial migrations — one row per Partial with source, target, reason.
• Failed migrations — one row per Failed with source, reason.
• Follow-ups suggested — aggregated feature gaps by blocker count, sorted descending, so unsupported source behavior is explicit.

​

Verify (dry-diff)

suchi import --from ./nightly-export --verify

• New — would be imported (no matching legacy_id).
• 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 legacy_id that isn’t in this bundle. Suggests a source-side deletion since the last export.

​

Shadow migration recipe