papermerge/papermerge-core: Open Source DMS with OCR for Scanned Documents

papermerge/papermerge-core: Open Source DMS with OCR for Scanned Documents

Developers and DevOps^{↗ Bright Coding Blog} teams managing digital archives face a persistent problem: scanned documents are images, not searchable text. Without OCR extraction, finding a specific invoice, contract, or receipt means manually browsing folders—or relying on brittle filename conventions. For organizations with thousands of scanned pages, this creates a searchable data gap that standard file storage doesn't solve. papermerge/papermerge-core addresses this directly. It's an open-source document management system that applies OCR to scans, indexes the extracted text, and exposes both a desktop-like web UI and a REST API for integration. Built in Python^{↗ Bright Coding Blog} and licensed under Apache 2.0, it targets teams that need long-term document storage with genuine searchability, not just cloud file hosting.

What is papermerge/papermerge-core?

papermerge/papermerge-core is the core backend, REST API server, and frontend UI for Papermerge DMS, an open-source document management system designed specifically for scanned documents—also referred to as digital archives. The project sits at the intersection of document storage, OCR processing, and full-text search indexing, with a web interface that deliberately mimics modern desktop file browsers rather than typical cloud-storage UIs.

The repository is actively maintained, with its last commit dated 2026-03-21. It has accumulated 508 GitHub stars and 109 forks, indicating modest but real adoption within the open-source community. Python is the primary language, which matters for backend developers evaluating extensibility and deployment complexity. The Apache License 2.0 allows commercial use, modification, and distribution with patent protection—standard for enterprise-friendly open-source projects.

Papermerge distinguishes itself from generic file storage through its OCR pipeline. It extracts text from PDF, TIFF, JPEG, and PNG files, then indexes that text for full-text search. This transforms image-based documents into queryable assets. The project also emphasizes UI familiarity: dual-panel browsing, drag-and-drop organization, hierarchical folders, and colored tags. For developers, the OpenAPI-compliant REST API enables programmatic access and integration with existing systems. The combination of a user-friendly frontend and a machine-accessible backend makes it suitable for both end-user workflows and automated document pipelines.

Key Features

The feature set of papermerge/papermerge-core reflects its focus on scanned document management rather than general file storage. These capabilities are documented in the repository and relevant to technical evaluation:

OCR and Text Extraction. The core value proposition. Papermerge runs OCR on uploaded documents, extracting searchable text from image-based PDFs, TIFFs, JPEGs, and PNGs. It also supports OCRed text overlay—users can download documents with the recognized text embedded, improving portability and compatibility with external tools.

Full-Text Search. Extracted text is indexed, enabling search across document contents rather than just filenames or metadata. This is paired with a search index management CLI (pm search build, pm search stats) for maintenance and rebuilding.

Desktop-Like Web UI. The interface provides dual-panel document browsing, drag-and-drop, and hierarchical folder structures. This design choice reduces friction for users accustomed to Windows Explorer or macOS Finder, lowering training overhead in organizational deployments.

Document Versioning. Multiple versions of a document can be maintained, supporting audit trails and recovery scenarios.

Document Types and Custom Fields. Documents can be categorized by type (e.g., "Invoice," "Contract"), with per-type custom metadata fields. This structured approach supports compliance and workflow automation.

Multi-User with Group Ownership and Sharing. Documents and folders can be owned by users or groups, with explicit sharing between users and groups. This supports organizational hierarchies and collaborative review workflows.

Page Management. Granular operations on document pages: delete, reorder, cut, move, and extract. This is particularly useful for cleaning up scanned batches or assembling documents from multiple sources.

Multi-Language UI. The interface is available in multiple languages, supporting international deployments.

OpenAPI-Compliant REST API. Full programmatic access for integration with external systems, custom frontends, or automated ingestion pipelines.

Use Cases

These scenarios are grounded in Papermerge's documented capabilities and represent realistic deployment contexts:

1. Small-to-Medium Business Document Archives Organizations receiving paper invoices, receipts, and contracts can scan, upload, and rely on OCR-based search rather than manual filing. The hierarchical folder structure and colored tags support departmental organization. Group ownership and sharing enable finance teams to collaborate on month-end reconciliation without email-based document passing.

2. Legal and Compliance Document Retention Law firms and regulated industries need long-term storage with audit trails. Document versioning, custom metadata fields per document type, and structured folder hierarchies support compliance requirements. The Apache 2.0 license permits on-premises deployment, addressing data sovereignty concerns that cloud-only solutions cannot.

3. Automated Ingestion Pipelines Developers can use the REST API to build automated workflows: scan documents via network scanners, POST to Papermerge, trigger OCR, and index for search. The pm CLI supports search index rebuilding after bulk imports, making it suitable for periodic batch processing or migration from legacy systems.

4. Personal Digital Archive Individual users with years of scanned tax documents, medical records, or correspondence can self-host Papermerge via Docker, avoiding subscription costs and maintaining full control. The desktop-like UI reduces the learning curve compared to database-driven or command-line archival tools.

5. Multi-Tenant Team Environments The combination of multi-user support, group ownership, and explicit sharing controls enables shared departmental archives without document sprawl. Unlike simple cloud storage, the document type system enforces consistent metadata capture across team members.

Installation & Setup

Papermerge provides Docker-based deployment for immediate use and a development environment for contributors. The commands below are reproduced exactly from the repository documentation.

Basic Docker Deployment

The fastest path to running Papermerge:

docker run -p 8000:80 \
    -e PAPERMERGE__SECURITY__SECRET_KEY=abc \
    -e PAPERMERGE__AUTH__PASSWORD=123 \
    papermerge/papermerge:3.5.3

This command:

• Maps host port 8000 to container port 80
• Sets a secret key for security signing (replace abc with a cryptographically secure value in production)
• Sets the admin authentication password (replace 123 accordingly)
• Pins to version 3.5.3 for reproducibility

For production or multi-service deployments, the documentation references Docker Compose scenarios at https://docs.papermerge.io/latest/setup/docker-compose/.

Backend Development^{↗ Bright Coding Blog} Setup

For contributors or those extending the backend:

# Install dependencies with uv
uv sync

Required environment variables (example with direnv):

export PM_DB_URL=postgresql↗ Bright Coding Blog://coco:***@127.0.0.1:5432/pmgdb
export PM_MEDIA_ROOT=/home/eugen/var/pmgdata
export PM_API_PREFIX='/api'

Start the backend server:

uv run task server

This starts the server on localhost:8000 with Swagger docs at http://localhost:8000/docs.

Frontend Development^{↗ Bright Coding Blog} Setup

cd frontend/

Required environment variables:

VITE_REMOTE_USER=admin
VITE_REMOTE_USER_ID=49e78737-7c6e-410f-ae27-315b04bdec69
VITE_REMOTE_GROUPS=admin
VITE_BASE_URL=http://localhost:8000
VITE_KEEP_UNUSED_DATA_FOR=1

Start the development server:

cd frontend
yarn workspace ui dev

The frontend runs at http://localhost:5173/. Adjust user ID and credentials to match your backend configuration.

Real Code Examples

The repository provides concrete commands for search index management and development workflow. These are the documented code examples available as of the last commit.

Search Index Rebuild

After bulk imports or when search behavior is inconsistent, rebuild the index from scratch:

pm search build

This clears existing index data and reprocesses all documents. Use during maintenance windows or after restoring from backup.

Search Index Statistics

Verify index health and document count:

pm search stats

This outputs statistics useful for debugging search coverage gaps or verifying ingestion pipeline completion.

Running Tests

For contributors validating changes:

# Install development dependencies
uv sync --group dev

# Execute test suite
uv pytest

The --group dev flag ensures test frameworks and fixtures are available.

Python Version Switching

For testing compatibility across Python versions:

uv sync --python 3.14

This switches the virtual environment to Python 3.14, useful for forward-compatibility verification.

Note: The README does not contain extensive API client code examples. Developers should refer to the OpenAPI/Swagger documentation at /docs for endpoint details and generate client libraries as needed.

Advanced Usage & Best Practices

Based on the tool's documented design, these practices are recommended for production deployments:

Secure the Secret Key. The PAPERMERGE__SECURITY__SECRET_KEY in Docker deployments must be cryptographically random in production. Hardcoded values like abc in the basic example are for demonstration only.

Use PostgreSQL for Production. The development environment variables reference PostgreSQL (PM_DB_URL=postgresql://...). SQLite or embedded databases are not documented; use PostgreSQL for concurrent multi-user scenarios.

Separate OCR Workers. The online demo explicitly notes it runs "very basic setup" without OCR workers. For production, deploy separate worker processes to handle OCR without blocking the web server. The Docker Compose documentation likely covers this topology.

Monitor Search Index Growth. Periodic pm search stats checks help anticipate storage needs. Rebuild indexes (pm search build) after major version upgrades or data migrations.

Version Pinning. The Docker example uses papermerge/papermerge:3.5.3. Pin to specific versions in production; latest tags introduce unpredictability.

Backup Media Root and Database. PM_MEDIA_ROOT contains the actual document files. Coordinate filesystem backups with database dumps for consistent recovery points.

Comparison with Alternatives

Trade-offs: Papermerge's desktop-like UI reduces training for non-technical users but may feel dated to those preferring modern SPA designs. Paperless-ngx has larger community momentum (more stars, broader ecosystem). Mayan EDMS offers more enterprise features but higher complexity. Papermerge occupies a middle ground: simpler deployment than Mayan, more explicit page management than Paperless-ngx, with a UI paradigm that prioritizes familiarity over trendiness.

FAQ

What file formats does Papermerge support? PDF, TIFF, JPEG, and PNG.

Is there a hosted version or only self-hosted? The project is self-hosted; a demo instance exists but resets every 24 hours.

What database is required? PostgreSQL, based on the documented PM_DB_URL format.

Does OCR run automatically on upload? The README implies OCR is a core feature; production deployments should use dedicated workers.

Is the REST API documented? Yes, OpenAPI-compliant docs are available at /docs on running instances.

Can I use this commercially? Yes, Apache License 2.0 permits commercial use.

How active is development? Last commit was 2026-03-21; 508 stars and 109 forks indicate steady maintenance.

Conclusion

papermerge/papermerge-core is a purpose-built open-source DMS for organizations and individuals who need searchable archives of scanned documents. Its combination of OCR, full-text search, desktop-like browsing, and programmatic API access addresses a specific gap that generic file storage leaves open. The Python codebase and Apache 2.0 licensing make it accessible for inspection, extension, and commercial deployment.

It is best suited for: teams with significant scanned document volumes, compliance-sensitive organizations needing on-premises control, and developers building automated document pipelines who want a backend with a usable default UI.

It is less suited for: users wanting cloud-native SaaS without infrastructure management, or those prioritizing cutting-edge UI frameworks over functional familiarity.

Explore the repository, try the Docker quickstart, and review the full documentation at https://docs.papermerge.io. For the latest code and to contribute, visit https://github.com/papermerge/papermerge-core.