Migrate from Paperless-ngx

Jiandu does not claim drop-in Paperless-ngx replacement. Plan the move as a verified import while the Paperless source remains available.

The browser importer accepts extracted document_exporter directories from stable Paperless-ngx 1.6.0 through 3.1.0. It recognizes the legacy markerless exports, version.json releases, and metadata.json releases. Prereleases, ZIP and data-only exports, and later versions are rejected. Paperless 3.x document-version and trash topology is flattened with explicit preflight loss records, so review those entries before committing the import.

Older exports store the document's creation date as a timestamp. Jiandu uses the calendar date written in that timestamp and reports the conversion in preflight. The export omits the Paperless installation timezone, so check dates near midnight against the source before cutover. The full timestamp is retained within the normal source-metadata bounds.

Imported titles, dates, correspondents, document types, and tags remain canonical metadata after ordinary processing and reprocessing. Native corrections and accepted household learning rules can change them.

Before importing

• Create and verify a Paperless backup using its own documented procedure.
• Keep the source read-only during the final migration window.
• Decide how correspondents, document types, tags, dates, notes, and custom fields should map.
• Identify restricted or unusually large documents for separate verification.
• Provision enough temporary space for both the export and imported originals.

SQLite only

The browser importer is available only with Jiandu's embedded SQLite backend. PostgreSQL 17 and 18 are supported for normal Jiandu operation but do not implement this provisional import path; Settings reports it unavailable. Do not treat a SQLite import as a stepping stone to PostgreSQL: Jiandu has no supported SQLite-to-PostgreSQL conversion or cross-backend restore.

Trial run

Import a representative subset first. Include scanned and digital PDFs, images, multiple correspondents and tags, unusual dates, and a document with access restrictions you will recreate.

1. Open the importer and select the extracted folder

Sign in with a role that has migration management and document create access. Bulk changes also require document read and update access. Open Settings, find Import from Paperless-ngx, and expand What will not carry over before choosing a source.

Select Choose export folder and choose the extracted exporter directory itself—the folder that contains manifest.json and, when present, its version marker. Do not select the parent directory or a ZIP file. Jiandu checks the metadata, supported source version, manifest JSON, file count, and total size in the browser before enabling Upload and check export.

Choose an Operation and select Add operation to build up to 16 ordered changes: add or remove tags, set or clear the sender (correspondent), or set or clear the kind (document type). These operations are immutable once the upload is created and apply only to documents created by this run; they never rewrite documents from an earlier import.

2. Upload and preflight without changing the library

Select Upload and check export. The byte counter is measured from durable upload offsets. Pause stops only the browser transfer. To continue, select Select folder and resume and choose the same unchanged folder; Jiandu validates its identity and resumes instead of creating a second workflow.

After all declared files arrive, the state advances through Waiting to check export and Checking export to Ready for your review. Preflight is read-only. Record these authoritative counts:

• documents found, new, already imported, skipped, conflicting, and mapped with changes;
• loss records and unsupported source records; and
• extra storage required.

Review every visible Information mapped with loss, Conflicts, and Unsupported source records group. When issue details are truncated, the totals remain authoritative; preserve the source export and migration evidence instead of assuming that the visible sample is complete. If any skip, conflict, unsupported record, or lossy mapping exists, Jiandu requires the explicit I reviewed… acknowledgement before enabling Start import.

Abort here if the source version, counts, storage requirement, or mapping differs from the written plan. Cancel and remove upload is available while uploading, at review, and after a failed preflight. It cancels the workflow and requests staging cleanup without modifying the source folder.

3. Start, observe, and recover safely

Select Start import only after accepting the preflight. The durable stages are Import queued, Rechecking immutable export, Importing documents, Applying bulk operations, and Verifying imported documents. Once import has started, the browser intentionally offers no cancel button: closing the dialog, reloading the page, or restarting Jiandu does not roll back already committed documents.

The importer reports when the current stage is safe to restart and reloads the latest workflow when Settings opens again. A stopped workflow shows its bounded failure message and Retry safely. Retry uses the same staged bytes, immutable bulk operations, and durable checkpoints; do not edit the export folder or begin a second import to work around a failure.

4. Reconcile the terminal result

Accept only Import complete or an understood Import complete with skips. Reconcile the terminal result against the recorded preflight: every source document must be accounted for as new, already imported, skipped, or conflicting, and every lossy or unsupported category must have an explicit disposition. Preserve the export and report if any count cannot be explained.

Then sample the result at the content boundary, not just in the list view:

1. open originals for each representative file type;
2. compare a known file digest or byte size with the Paperless export;
3. inspect titles, dates, correspondents, document types, tags, notes, and custom-field mappings;
4. search for terms a household member would actually remember; and
5. recreate and test any access restriction, because Paperless authorization behavior is not imported as Jiandu policy.

Record the source export version, preflight counts, terminal state, exceptions, and mapping choices so the final run is repeatable. Use Import another export only after reconciliation is complete.

Cutover

Pause changes in Paperless, take a final export, and repeat the proven browser sequence. Keep Paperless available read-only until Jiandu has passed the agreed verification and at least one full backup/restore drill.

If an item fails, preserve the migration report, workflow state, and exact bounded error. Do not delete the source item to make counts line up.

For the server-reported version range and loss contract, see the generated Paperless import profile operation.