Migrating from Paperless

If you kept your papers in Paperless by Mariner Software, this page is for you. Mariner is gone, Paperless is unmaintained, and macOS now warns you at launch that it won't work with macOS 28. That's about a year away. When it arrives, the app stops opening, and your documents are sealed inside a library only that app could read.

DocuCasa began exactly there. It was built as a new home for a 17 year, 2,800 document Paperless library, and the migration tool on this page is the same one that moved it. It reads your Paperless library directly, rebuilds your folders and tags in a DocuCasa vault, copies every file, and then verifies every copy byte for byte against the original.

Honesty first

This tool is offered as is. It worked, completely, on one large real library. Mine. Your library is older or newer, bigger or smaller, healthier or stranger than mine, and I can't promise it will work for you. Here is what I can promise. It never writes to your Paperless library, and you'll run it on a copy anyway. Trying it risks nothing.

What you need

The tool. One Python file, small enough to read.
Download the migration tool
Your browser puts it in your Downloads folder unless you've told it otherwise.
Your Paperless library, and its password if it's encrypted. Without the password, nothing can read it, including this tool.
Python 3. Type python3 --version in Terminal. If your Mac offers to install developer tools, accept.
Comfort pasting commands into Terminal. Every command you need is on this page.

What comes across, and what doesn't

Folders, tags, dates, titles, amounts, and every document file, verified byte for byte. Notes come across. Saved searches don't. Anything on disk that Paperless forgot about is collected into an Unfiled folder rather than left behind.

The steps

Copy your library. In Finder, click your .paperless file once and press ⌘D. The tool only ever reads, but you'll work on the copy anyway. That's just good manners with your own history.
Open the copy and find your source. Right click the copy and choose Show Package Contents.
- If you see a file named DocumentWallet.documentwalletsql and a folder named Documents, your library is not encrypted, and the copy itself is your source. Whenever a command below needs the source path, drag the copy of your .paperless file straight into the Terminal window and its path fills itself in.
- If you see ReceiptWalletEncryptedData.sparsebundle, your library is encrypted. Double click it, enter your Paperless password, and it mounts as a volume. That mounted volume is your source. Type ls /Volumes in Terminal to see its name.
Create an empty vault. Paste this into Terminal. It asks you to choose a password, and from this moment the rule applies. If you forget it, nothing can recover your documents.
```
hdiutil create -type SPARSEBUNDLE -fs APFS -encryption AES-256 -size 50g -volname Home ~/Desktop/Home.sparsebundle && mv ~/Desktop/Home.sparsebundle ~/Desktop/Home.docucasa
```
Then mount it.
```
hdiutil attach ~/Desktop/Home.docucasa
```
The 50g is a ceiling, not a claim. The file only ever grows as large as your documents actually are.
Dry run. Move Terminal into the folder holding the tool. Paste cd ~/Downloads, or type cd and drag the folder in. Then run the tool against your source. Type the command up to and including --source , then drag your source into the Terminal window and its path fills itself in.
```
python3 docucasa-paperless-migration.py --source /Volumes/YourSource
```
An output folder appears next to the tool with two files, the migration plan and the anomaly report. Open both and look them over. Nothing has been copied yet.
The real run. Same command, plus the destination and the word that makes it real.
```
python3 docucasa-paperless-migration.py --source /Volumes/YourSource --dest /Volumes/Home --execute
```
The tool copies every document, builds the index, and then verifies every copy byte for byte against the original.
Open your new vault. Eject both volumes in Finder. Download DocuCasa, choose Open an Existing Vault, and pick Home.docucasa on your Desktop. Your papers are home. When you're satisfied, move the vault anywhere you like, except a cloud synced folder.

If it goes wrong

The anomaly report lists what the tool couldn't handle, in plain rows. These directions are all the support there is, and for a free tool I can't promise more. But if the tool fails on your library, write to me anyway. No promises, but I'd like to know what a library that defeats it looks like.