ciur/papermerge: Open-Source OCR Document Management for Digital Archives

ciur/papermerge: Open-Source OCR Document Management for Digital Archives

Organizations drowning in paper records face a predictable technical challenge: converting static scanned documents into searchable, structured digital archives without proprietary lock-in. ciur/papermerge addresses this directly—an open-source document management system built in Python^{↗ Bright Coding Blog} that applies OCR extraction, full-text indexing, and hierarchical organization to scanned PDFs, TIFFs, JPEGs, and PNGs. With 2,932 GitHub stars and active development through late 2025, it offers a web-based alternative to commercial DMS platforms for teams that need control over their document pipeline.

What is ciur/papermerge?

ciur/papermerge is an open-source document management system (DMS) designed specifically for digital archives—collections of scanned documents that require OCR processing, text indexing, and long-term storage. The project is maintained by Eugen Ciur (username: ciur) and released under the Apache License 2.0, with Python as its primary implementation language.

The repository at ciur/papermerge serves a specific architectural purpose: it is a meta-repository that tracks project status, existence, and issues rather than containing application source code. As the project scaled, development was split across multiple repositories under the Papermerge GitHub Organization, with core backend logic residing in papermerge/papermerge-core.

This structure reflects mature open-source governance—separating concerns between issue tracking, REST API development, and documentation. The last commit as of November 23, 2025 indicates sustained maintenance, while 308 forks suggest active community engagement beyond passive stargazing.

Papermerge's positioning is deliberately narrow and technically precise: long-term storage of digital archives. It does not attempt to be a generic content management system or collaborative editing platform. Instead, it optimizes for a specific workflow: ingest scanned documents → OCR extract text → index for search → organize with folders, tags, and metadata → retrieve via desktop-like web interface or REST API.

Key Features

OCR Pipeline with Text Overlay Papermerge extracts text from scanned documents using OCR and generates downloadable documents with OCRed text overlay. This transforms image-based PDFs into partially machine-readable files without destroying the original visual layout—a critical requirement for legal and compliance archives.

Desktop-Like Web Interface The UI mimics modern file browsers with dual-panel document browsing, drag-and-drop operations, and hierarchical folder structures. For users accustomed to Windows Explorer or macOS Finder, this reduces training friction compared to traditional web-based DMS interfaces.

Full-Text Search Indexed OCR output enables searching across document contents, not just filenames or metadata. This is the core value proposition for digital archives: making decades of scanned records queryable in seconds.

Document Versioning Multiple versions of the same document can be tracked, supporting audit trails and iterative corrections without duplicating files.

Flexible Metadata System

• Document Types (Categories): Classify documents by semantic type
• Custom Fields: Attach structured metadata per document type
• Colored Tags: Visual organization markers for documents and folders

Page-Level Operations Granular manipulation including delete, reorder, cut, move, and extract pages—essential for cleaning up multi-page scans or assembling composite documents from different sources.

OpenAPI-Compliant REST API The backend exposes a standardized REST API, enabling integration with existing workflows, custom frontends, or automated ingestion pipelines.

Multi-User Support Role-based access for teams managing shared document collections.

Format Support PDF, TIFF, JPEG, and PNG—covering the vast majority of scanned document sources.

Use Cases

1. Legal and Compliance Document Retention Law firms and regulated industries must maintain searchable archives of signed contracts, correspondence, and filings for years or decades. Papermerge's OCR + full-text search + versioning satisfies discovery and audit requirements without per-seat licensing costs of commercial DMS platforms.

2. Small-to-Medium Business Paperless Transition Organizations with filing cabinets of invoices, receipts, and personnel records can batch-scan, ingest into Papermerge, and eliminate physical storage. The desktop-like UI reduces adoption resistance from non-technical staff.

3. Historical Archive Digitization Libraries and museums scanning brittle periodicals, manuscripts, or photographs need preservation-grade storage with searchability. Page management features allow curators to correct scan order errors without re-scanning entire volumes.

4. Automated Invoice Processing Pipeline Using the REST API, DevOps^{↗ Bright Coding Blog} teams can build ingestion workflows: scan → upload via API → OCR extract → tag by vendor document type → route to accounting system. Custom fields capture invoice numbers, dates, and amounts for structured export.

5. Personal Document Management Individual developers or small households can self-host a private alternative to cloud scanning services, retaining full control over sensitive financial and medical records.

Installation & Setup

Important architectural note: The ciur/papermerge repository is a meta-repository. Source code for the application resides in papermerge/papermerge-core. The installation process documented below reflects the standard deployment pattern for the Papermerge ecosystem based on project documentation at https://docs.papermerge.io.

Papermerge deploys as web-based software—there is no executable installer. It requires a web server and is accessed through a browser.

Prerequisites

• Docker^{↗ Bright Coding Blog} and Docker Compose (recommended path)
• Or: Python 3.10+, PostgreSQL^{↗ Bright Coding Blog}, Redis, Tesseract OCR

Docker Deployment (Recommended)

# Clone the core repository
git clone https://github.com/papermerge/papermerge-core.git
cd papermerge-core

# Copy and configure environment variables
cp .env.example .env
# Edit .env to set database credentials, secret key, and storage paths

# Start services
docker-compose up -d

The Docker Compose configuration orchestrates:

• Web application container: Django-based backend with web UI
• PostgreSQL: Document metadata and user data
• Redis: Task queue for asynchronous OCR jobs
• Tesseract OCR engine: Text extraction from scanned images

Manual Installation (Advanced)

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install core package
pip install papermerge-core

# Initialize database
papermerge manage migrate

# Create superuser
papermerge manage createsuperuser

# Start development server
papermerge manage runserver

Post-Installation Configuration

1. OCR Language Packs: Install Tesseract language data for non-English documents:

   # Ubuntu/Debian
   sudo apt-get install tesseract-ocr-deu tesseract-ocr-fra
   

2. Storage Backend: Configure local filesystem or S3-compatible object storage in .env for document persistence.

   Advertisement

3. Worker Processes: For production deployments, run Celery workers to process OCR tasks asynchronously:

   celery -A config worker -l info
   

Real Code Examples

The README does not contain extensive code samples. The following examples are derived from the documented REST API and standard patterns for interacting with OpenAPI-compliant backends. Where specific syntax is inferred from architecture rather than explicitly documented, this is noted.

Example 1: Upload Document via REST API

# Obtain authentication token (standard Django REST framework pattern)
curl -X POST https://your-papermerge-instance.com/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "your-user", "password": "your-pass"}'

# Upload PDF for OCR processing
curl -X POST https://your-papermerge-instance.com/api/documents/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/scan.pdf" \
  -F "title=Invoice_2024_001" \
  -F "document_type=Invoice"

Note: Exact endpoint paths should be verified against the current OpenAPI schema at /api/schema/ or interactive documentation at /api/docs/ on your instance.

Example 2: Query Documents by Tag

# Search for documents tagged 'urgent' in 'invoices' folder
curl -G https://your-papermerge-instance.com/api/documents/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "tags=urgent" \
  --data-urlencode "folder__title=invoices"

Example 3: Python Client Pattern (Inferred from OpenAPI Compliance)

import requests

class PapermergeClient:
    def __init__(self, base_url, token):
        self.base_url = base_url.rstrip('/')
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    
    def create_folder(self, title, parent_id=None):
        """Create hierarchical folder structure."""
        payload = {'title': title}
        if parent_id:
            payload['parent_id'] = parent_id
        
        response = requests.post(
            f'{self.base_url}/api/folders/',
            headers=self.headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()
    
    def get_document_text(self, document_id):
        """Retrieve OCR-extracted text for full-text indexing verification."""
        response = requests.get(
            f'{self.base_url}/api/documents/{document_id}/text/',
            headers=self.headers
        )
        return response.json().get('text', '')

# Usage
client = PapermergeClient('https://papermerge.example.com', 'your-token')
folder = client.create_folder('Q4-2024-Invoices', parent_id='folder-uuid-here')

This Python example reflects standard REST client patterns compatible with OpenAPI specifications. Verify field names against the live schema, as the README does not provide explicit API documentation.

Advanced Usage & Best Practices

Asynchronous OCR Scaling For high-volume ingestion, deploy multiple Celery workers across nodes with shared Redis broker. OCR is CPU-intensive; isolate worker pools from web serving infrastructure to prevent request latency spikes during batch imports.

Document Type Design Define document types and custom fields before bulk import. Retrofitting metadata schemas to thousands of existing documents requires API scripting. Common patterns: Invoice (fields: vendor, amount, due_date), Contract (fields: counterparty, effective_date, expiration_date), Correspondence (fields: sender, date_received).

Backup Strategy Separate database (PostgreSQL) and document storage backups. Document files are immutable after upload—incremental backups capture only new additions. Database dumps include folder hierarchies, tags, and metadata essential for reconstruction.

Performance Considerations The README does not specify throughput benchmarks. Based on architecture, expect OCR latency proportional to Tesseract performance per page. For sub-second search, ensure PostgreSQL full-text search indexes are maintained; consider dedicated search backends (Elasticsearch, Meilisearch) if scaling beyond thousands of documents, though this would require custom integration.

Security Hardening Run behind reverse proxy (nginx, Traefik) with TLS termination. The web UI supports multi-user authentication—enable MFA at proxy level if not natively supported. Restrict file storage directory permissions to application user only.

Comparison with Alternatives

Trade-off Analysis

• vs. Paperless-ngx: Papermerge offers superior page-level manipulation and structured metadata, but Paperless-ngx prioritizes simpler setup for individual users. Choose Papermerge when organizational hierarchy and document types matter; choose Paperless-ngx for personal rapid deployment.

• vs. Mayan EDMS: Mayan provides more extensive workflow automation and enterprise features, but with steeper operational complexity. Papermerge's desktop-like UI reduces training burden for non-technical users migrating from Windows file shares.

[INTERNAL_LINK: self-hosted-document-management-comparison]

FAQ

Q: Is ciur/papermerge the actual application code? A: No—it is a meta-repository for tracking issues and project status. Source code is in papermerge/papermerge-core.

Q: What license covers use in commercial environments? A: Apache License 2.0, permitting commercial use with attribution.

Q: Can I run Papermerge without Docker? A: Yes, but requires manual Python environment setup with PostgreSQL, Redis, and Tesseract dependencies.

Q: Does OCR support non-Latin scripts? A: Tesseract supports 100+ languages; install appropriate language packs on the host system.

Q: Is there a hosted/SaaS version? A: The README does not mention official SaaS. Self-hosting is the documented deployment model.

Q: How does search scale with document volume? A: PostgreSQL full-text search is default; performance beyond tens of thousands of documents may require architecture evaluation not covered in README.

Q: Can I migrate from another DMS? A: REST API enables scripted migration, but no specific importers are documented—custom development required.

Conclusion

ciur/papermerge occupies a well-defined niche in the open-source DMS landscape: OCR-enabled archival of scanned documents with an interface that respects users' existing mental models. It is not the simplest tool for individual paperless conversion, nor the most feature-complete enterprise platform. For teams needing structured metadata, page-level control, and full-text search across digitized records—without proprietary licensing—it delivers specific, credible value.

The project's architectural maturity (separated repositories, OpenAPI compliance, active maintenance through 2025) suggests sustainable development. Developers evaluating self-hosted document solutions should weigh Papermerge when user adoption friction and long-term archival searchability are primary concerns.

Explore the project, review open issues, and evaluate the live demo at https://demo.papermerge.com (username: demo, password: demo). The source meta-repository and issue tracker remain at https://github.com/ciur/papermerge—start there for project status, then dive into papermerge/papermerge-core for technical contribution.