How to Export a OneNote File to PDF in Python

Aspose.Note FOSS for Python enables programmatic PDF export of Microsoft OneNote .one section files without requiring Microsoft Office or any operating-system-level document converter. Export is handled by the Document.Save() method backed by the optional ReportLab PDF renderer.

Benefits

1. Server-friendly: runs on any OS, including headless Linux servers and CI/CD containers
2. Stream-capable: save directly to an io.BytesIO buffer, no temporary file needed
3. Tag icon support: render NoteTag icons alongside tagged content using custom icon directories
4. Free and open-source: MIT license

Prerequisites

PDF export requires the optional ReportLab dependency. Install it via the [pdf] extra:

pip install "aspose-note[pdf]"

If you already have aspose-note installed without the extra:

pip install --upgrade "aspose-note[pdf]"

Verify that ReportLab is available:

python -c "import reportlab; print(reportlab.Version)"

Step-by-Step Guide

pip install "aspose-note[pdf]"

from aspose.note import Document, SaveFormat
print("Ready for PDF export.")

from aspose.note import Document

doc = Document("MyNotes.one")
print(f"Section: {doc.DisplayName}")
print(f"Pages:   {doc.Count()}")

from aspose.note import Document, SaveFormat

doc = Document("MyNotes.one")
doc.Save("output.pdf", SaveFormat.Pdf)
print("PDF saved to output.pdf")

from aspose.note import Document, PdfSaveOptions, SaveFormat

doc = Document("TaggedNotes.one")

opts = PdfSaveOptions(SaveFormat.Pdf)
opts.TagIconDir = "./icons"   # directory of PNG/JPEG icon files
opts.TagIconSize = 12.0       # size in points
opts.TagIconGap  = 3.0        # padding in points

doc.Save("tagged_output.pdf", opts)

import io
from aspose.note import Document, PdfSaveOptions, SaveFormat

doc = Document("MyNotes.one")

buf = io.BytesIO()
doc.Save(buf, PdfSaveOptions(SaveFormat.Pdf))
pdf_bytes = buf.getvalue()
print(f"PDF size: {len(pdf_bytes)} bytes")

from pathlib import Path
from aspose.note import Document, SaveFormat

input_dir = Path("./onenote_files")
output_dir = Path("./pdf_output")
output_dir.mkdir(exist_ok=True)

for one_file in input_dir.glob("*.one"):
    doc = Document(str(one_file))
    out_path = output_dir / one_file.with_suffix(".pdf").name
    doc.Save(str(out_path), SaveFormat.Pdf)
    print(f"Exported: {one_file.name} -> {out_path.name}")

Common Issues and Fixes

1. ImportError: No module named ‘reportlab’

Cause: The [pdf] extra was not installed.

Fix:

pip install "aspose-note[pdf]"

2. UnsupportedSaveFormatException

Cause: A SaveFormat other than Pdf was passed (e.g. SaveFormat.Html, SaveFormat.Jpeg). Only SaveFormat.Pdf is implemented.

Fix: Always use SaveFormat.Pdf for export. Other formats are declared for API compatibility but raise UnsupportedSaveFormatException.

3. IncorrectPasswordException

Cause: The .one file is encrypted. Encrypted documents are not supported.

Fix: Use an unencrypted .one file. The commercial Aspose.Note product supports encryption.

4. FileNotFoundError

Cause: The input .one file path is incorrect.

Fix: Use pathlib.Path.exists() to validate before loading:

from pathlib import Path
from aspose.note import Document, SaveFormat

path = Path("MyNotes.one")
assert path.exists(), f"File not found: {path.resolve()}"
doc = Document(str(path))
doc.Save("output.pdf", SaveFormat.Pdf)

5. Output PDF is blank or empty

Cause: The .one file contains pages but no text content (only images or tables with no text). The PDF renderer produces pages based on what ReportLab can render from the DOM.

Fix: Verify page content before exporting:

from aspose.note import Document, RichText

doc = Document("MyNotes.one")
text_count = len(doc.GetChildNodes(RichText))
print(f"RichText nodes found: {text_count}")

Frequently Asked Questions

Which save formats are supported?

Only SaveFormat.Pdf is currently implemented. SaveFormat.Html, SaveFormat.One, SaveFormat.Jpeg, SaveFormat.Png, SaveFormat.Gif, SaveFormat.Bmp, and SaveFormat.Tiff are declared for API compatibility but raise UnsupportedSaveFormatException.

Can I export to a stream instead of a file?

Yes. Document.Save() accepts any writable binary stream as its first argument:

import io
from aspose.note import Document, PdfSaveOptions, SaveFormat

doc = Document("MyNotes.one")
buf = io.BytesIO()
doc.Save(buf, PdfSaveOptions(SaveFormat.Pdf))
pdf_bytes = buf.getvalue()

Does export preserve page order?

Yes. Pages are exported in the same order they appear in the DOM (the order returned by iterating the Document).

Is PDF export available on Linux?

Yes. ReportLab and Aspose.Note FOSS for Python are both OS-independent.

Can I export a subset of pages?

PdfSaveOptions.PageIndex and PageCount fields exist but are not forwarded to the PDF exporter in v26.2 and have no effect: the entire document is always exported.

Related Resources:

• How to Extract Text from OneNote Files
• Features Overview
• Installation Guide
• API Reference