pawpyrus 2025.2.27.0

A minimalist paper data storage based on QR codes

Description

Pawpyrus is a minimalist open-source paper data storage based on QR codes and ArUco. It generates a PDF from any small-sized binary file (recommended size <100kb). Further, the paper data storage can be scanned and decoded (recommended resolution 300dpi).

It can be useful if you need to backup data on paper:

• Encryption keys (e.g. GnuPG)
• File-based password databases (e.g. KeePassXC)
• Cryptocurrency wallets

Installation

The script is pure Python and a part of PyPI, so can be installed via pip:

python3 -m pip install pawpyrus

Usage

Encoder:

pawpyrus Encode -n "Description" -i  "input.file" -o "output.pdf"

Also, pawpyrus can read data from stdin. For example, encoding GPG public keys:

gpg --export 0xDEADBEEF | pawpyrus Encode -n "My pubkey" -i - -o "my-pubkey.pdf"

Decoder:

pawpyrus Decode -i "scan1.jpg" "scan2.png" "scan3.jpg" "masked/too/*.png" -o "output.file"

Data Format

Pawpyrus uses a custom alphanumeric encoding, which is designed to store information in QR code quite effectively. For now, that makes 4.3kb per A4 page (pixel size 0.6 mm).

Got a Trouble?

QR and ArUco detectors may fail on one or several blocks. The situation is totally normal, although uncomfortable. It's fixed for now, with two detectors (opencv and pyzbar) instead of one, but the bug may reappear in some circumstances. That's why Debug Mode was implemented:

pawpyrus Decode -d "debug_dir" -i "scan1.jpg" "scan2.jpg" "scan3.jpg" -o "output.file"

With Debug Mode, you can inspect undetected QR codes, read them manually with any device you have, and create a file with text blocks which can be processed as well:

pawpyrus Decode "scan1.jpg" "scan2.jpg" "scan3.jpg" -t "unrecognized_codes.txt" -o "output.file"

If you have any idea how to fix the bug better, give me a clue.

Similar Projects

1. intra2net/paperbackup
2. Paperback by Olly and Wikinaut/paperback-cli
3. colorsafe/colorsafe
4. Twibright Optar
5. Paperkey
6. 4bitfocus/asc-key-to-qr-code