Skip to main content
Use suchi export when you want a portable archive of document originals and the metadata supported by Suchi sidecars. For disaster recovery or an exact instance migration, use a complete DATA_DIR backup instead. A portable export does not contain users, settings, audit history, or every document field.

​
Export the source archive

Run the command with the source instance’s DATA_DIR configuration:
By default this selects original system 1 and its live documents owned by the first admin account. Choose the target and owner scope explicitly:
Trashed documents are excluded. Check the archive before moving it:
The zip contains original files and matching JSON sidecars under documents/. The files under taxonomy/ are reference dumps; they are not automatically installed by the restore process. Manifest version "2" identifies the selected system code/name; --all means all owners there, not all systems. Sidecar format stays 1 with optional jd_system and jd_address. Those record the source, not an ID-preserving restore protocol.

​
Prepare the fresh instance

  1. Start the target and complete first-run account setup.
  2. Apply the target filing tree before ingesting documents. For a named export, introduce the same target code through a prefixed taxonomy import first. Sidecar jd_system must match the watcher target; it cannot create or route a system. Category codes resolve there; an absent code falls back to its Inbox.
  3. Grant the intended owner entry and configure the watcher for that target.
The watcher can be configured in Settings, or with environment variables:
When using environment variables, restart Suchi after the owner account exists. At startup, the watcher must be able to resolve INGEST_FS_OWNER_EMAIL to an enabled user. Omit INGEST_FS_SYSTEM only when intentionally targeting the original system. Documents may receive new IDs and addresses. Memberships, ACLs and relationships are not reconstructed by sidecars; exact restoration requires a whole-instance backup.

​
Restore the documents

Extract outside the active staging directory:
Copy sidecars first, then originals. This prevents the watcher from ingesting an original during a copy before its metadata file is visible:
Do not use suchi import --from for this zip. That command consumes a Paperless-compatible Django manifest, not the native Suchi export format. The watcher removes successfully consumed originals and sidecars. Follow the server logs for fswatch.ingested, and inspect /srv/suchi-staging/errors/ for a rejected file and its .err companion. Dropping the same export again into the same system for the same owner is document-safe: live documents deduplicate by SHA-256. Another system receives distinct document rows even if immutable CAS bytes are shared. A duplicate drop does not update metadata; edit existing records through Suchi.

​
What survives the round trip

For those omitted fields, or when the exact taxonomy and user configuration must survive, restore a complete DATA_DIR backup.

​
Verify the target

Confirm the document count and open samples from each important file type. Check their title, source date, filing category, tags, and correspondent roles. Then verify the content-addressed store:
After verification, remove the extracted working directory and protect or delete the export according to the archive’s data-retention policy.