supernote

All-in-one toolkit for Supernote devices: parse notebooks, self host, and access services.

This content is shared between the documentation and github repository at github.com/allenporter/supernote-lite.

Features

• Notebook Parsing: Convert .note files to PDF, PNG, SVG, or text
• Private Server: Self-hosted Supernote Private Cloud implementation
• Client: Interact with Supernote (Private) Cloud API

Installation

# Install specific components
pip install supernote              # Notebook parsing only
pip install supernote[server]      # + Private server
pip install supernote[client]      # + Client

# Full installation (recommended for server users)
pip install supernote[all]

Local Development Setup

To set up the project for development, please refer to the Contributing Guide.

Quick Start

Parse a Notebook

from supernote.notebook import parse_notebook

notebook = parse_notebook("mynote.note")
notebook.to_pdf("output.pdf")

The notebook parser is a fork and slightly lighter dependency version of supernote-tool that drops svg dependencies not found in some containers. Generally, you should probably prefer to use that original library unless there is a specific reason you're also having a similar dependency limitation. All credit goes to the original authors of supernote-tool for providing an amazing low level utility.

Server Setup & Bootstrap

1. Start the Server:

   supernote serve

2. Register the Admin: The first user registered becomes the system administrator.

   supernote admin user add [email protected] --url http://localhost:8080

3. Login to CLI:

   supernote cloud-login [email protected] --url http://localhost:8080

See the Bootstrap Guide for detailed deployment and security instructions.

Run with Docker

# Build image
docker build -t supernote .

# Run server
docker run -d -p 8080:8080 -v $(pwd)/storage:/storage supernote serve

See Server Documentation for details.

Access Supernote Services

from supernote.client import SupernoteClient

async with SupernoteClient.from_credentials(email, password) as client:
    files = await client.list_files()

CLI Usage

# Notebook operations
supernote notebook convert input.note output.pdf
supernote notebook analyze input.note

# Server operations
supernote serve
supernote admin user list
supernote admin user add [email protected]

# Client operations
supernote cloud-login --url http://localhost:8080 [email protected]
supernote cloud-ls

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Local development setup
• Project architecture
• Coding standards
• Running tests

Credits

The supernote library is a fork and slightly lighter dependency version of supernote-tool that drops svg dependencies not found in some containers. Generally, you should probably prefer to use that library unless there is a specific reason you're also having a similar dependency limitation.

Acknowledgments

This project is in support of the amazing Ratta Supernote product and community. This project aims to be a complementary, unofficial offering that is compatible with the Private Cloud feature, helping to support their open ecosystem, helping to reduce load on their servers etc (e.g. for AI powered personal assistant integrations that need to process notebooks, etc)

Comparison with Official Private Cloud

Ratta offers an official Private Cloud solution based on Docker. You should generally prefer that solution, unless you are interested in lower level integrations and are comfortable managing your own security, SSL, etc.

Here is how this project compares:

Feature	Official Private Cloud	Supernote-Lite (This Project)
Type	Official Product	Community Project
Technology	Docker Container (Java/Spring)	Python Package
Source	Closed Source	Open Source
Focus	Stability & End-Users	Hackability & Developers
Requirements	Docker Environment	Python 3.10+
Extensibility	Low (Black Box)	High (Modular Codebase)
Security/SSL	Documented Guides Included	DIY (Bring Your Own Proxy)

Use the Official Private Cloud if:

• You want a supported, "set-and-forget" solution.
• You prefer using Docker containers.

Use Supernote-Lite if:

• You want to understand how the protocol works.
• You want to run on low-power hardware without Docker overhead.
• You want to integrate Supernote sync into your own Python applications.
• You want to customize the server behavior.

Community Projects

• github.com/jya-dev/supernote-tool - Unofficial python tool for Ratta Supernote for parsing notebook files, which this projects notebook module is based on.
• github.com/philips/supernote-typescript - Supernote file-format support in typescript
• github.com/julianprester/sncloud - Supernote Cloud API for Python
• github.com/fharper/awesome-supernote - A curated list of Supernote resources
• github.com/philips/supernote-obsidian-plugin - Obsidian plugin for Supernote
• github.com/jbchouinard/supernote-sync - Tool to automatically backup files from the Supernote using local WiFi using the Supernote Browse & Access feature
• github.com/theburningbush/snbackup - CLI tool for wireless Supernote backups using the Browse & Access feature
• github.com/dsummersl/sn2md - Supernote to text/image converter (sn2md)
• github.com/calebc42/eink-template-gen - Generates pixel-perfect page templates for e-ink devices.