A cross-platform book management application

---

Overview

Papyrus is an open-source, cross-platform application for managing and reading books. It supports both physical and digital book collections across Android, iOS, Web, Windows and Linux. The application features an integrated book reader, flexible organization tools, reading statistics, progress tracking, uses local media caches and optional Papyrus server storage and cross-device synchronization via a self-hostable server.

Why Papyrus?

Many reading applications offer partial solutions but fall short on essential features, platform availability or user experience. Papyrus aims to deliver a comprehensive, privacy oriented solution that:

• Works offline-first with optional cloud synchronization
• Supports self-hosting for complete data ownership
• Provides a unified experience across all popular platforms
• Offers extensive customization for different reading preferences

Features

Category	Features
Reading	EPUB/PDF reader with pagination/scrolling, appearance settings and saved positions
Organization	Shelves, tags/topics and library filters
Annotations	Book-level bookmarks, notes and annotations; reader text selection/export is future work
Progress	Saved progress, reading sessions and statistics
Goals	Reading goals and progress views
Sync	Offline-first local library and optional self-hosted PowerSync synchronization
Storage	Local media caches and Papyrus-managed server uploads
Catalogs	OPDS 1.2/2.0 browsing, search and imports through the backend relay
Accessibility	E-ink, light/dark themes and reader typography controls

The built-in reader opens EPUB and PDF. Native metadata import also accepts MOBI, AZW3, TXT, CBR and CBZ; these formats do not have reading engines yet. The web file picker currently accepts EPUB. Additional cloud storage providers and selection-based reader annotations remain future work.

Supported platforms

• Android
• iOS
• macOS
• Linux
• Windows
• Web

Getting started

Prerequisites

• Flutter 3.41.2, matching the CI SDK: installation guide

Installation

Important

For instructions on setting up the full development environment on your platform, see PapyrusReader/papyrus.

1. Clone the repository

   git clone git@github.com:PapyrusReader/client.git
   cd client

2. Install dependencies

   cd app
   flutter pub get --enforce-lockfile

3. Run the application

   # Android/iOS (with connected device or emulator)
   flutter run
   
   # Web
   flutter run -d chrome
   
   # Desktop
   flutter run -d windows  # or: macos, linux

Running with the back-end

When the user signs in, the Flutter client communicates with the Papyrus server for auth and asks the server for PowerSync credentials.

Run the server and PowerSync locally, then start Flutter with:

cd ../server
./scripts/bootstrap_local.sh
cd ../client/app
flutter run -d chrome --web-hostname papyrus.localhost --web-port 3000 --dart-define-from-file=.dart_defines

For local web auth links, add these entries to /etc/hosts:

127.0.0.1 papyrus.localhost
::1 papyrus.localhost

Documentation

See PapyrusReader/docs.

Technology stack

Layer	Technology
Frontend	Flutter / Dart
Backend	FastAPI / Python
Database	PostgreSQL
Local database	SQLite / PowerSync
File storage	Device cache (OPFS on web) and Papyrus server

Contributing

Join the Papyrus Slack community to meet contributors, ask questions, and discuss development across the PapyrusReader repositories. Start in #announcements, introduce yourself in #introductions, and collaborate in #development. Please follow our Code of Conduct.

Keep actionable bug reports and technical decisions in GitHub issues and pull requests so they remain easy to find.

Setup

1. Fork and clone the repository

2. Install dependencies from app/ using the Flutter version in CI (currently 3.41.2):

   cd app
   flutter pub get --enforce-lockfile

   When using the full Papyrus workspace, run tools/papyrus sdk and tools/papyrus deps client from its root. The workspace includes pinned SDK wrappers, VS Code check/test tasks, project skills, and Dart MCP integration. See its development tooling guide.

Development workflow

1. Create a feature branch:

   git checkout -b feature/your-feature-name

2. Make your changes and ensure quality checks pass:

   dart format --output=none --set-exit-if-changed .
   flutter analyze --no-fatal-warnings --no-fatal-infos
   flutter test
   node --test test/web/flutter_bootstrap_test.cjs

3. Commit your changes and push:

   git commit -m "feat: description of your changes"
   git push origin feature/your-feature-name

4. Open a pull request

Resources

Repository	Description
server	Back-end for self-hosted sync and file storage
reader	Book file viewer library
website	Landing page
docs	Documentation
papyrus	Development workspace