Importing from Microsoft OneNote

Ce contenu n’est pas encore disponible dans votre langue.

Butterfly can convert Microsoft OneNote sections and packaged notebooks into Butterfly documents.

Supported file types

Butterfly supports these OneNote formats:

.one — a single OneNote section
.onepkg — a packaged OneNote notebook containing multiple sections and section groups

For transferring an entire notebook, .onepkg is usually the most convenient format. Use .one when you only want to transfer one section.

Butterfly does not currently import loose .onetoc2 files or a ZIP file downloaded from OneNote for the web directly.

Exporting from the OneNote desktop app

The instructions below apply to the OneNote desktop application on Windows, as included with Microsoft 365 and recent desktop versions of Microsoft Office.

Before exporting, allow OneNote to finish synchronizing the notebook. This is especially important for notebooks stored in OneDrive or SharePoint.

Exporting an entire notebook

Open the notebook in the OneNote desktop application.
Select File in the upper-left corner.
Select Export.
Under Export Current, select Notebook.
Under Select Format, select OneNote Package (*.onepkg).
Select Export.
Choose a local folder and enter a name for the exported file.
Select Save.

You can now import the resulting .onepkg file into Butterfly.

The package contains the notebook’s sections and section groups. Butterfly uses this structure when naming and organizing the imported pages.

Exporting a single section

Open the notebook in the OneNote desktop application.
Select the section that you want to export.
Select File.
Select Export.
Under Export Current, select Section.
Under Select Format, select OneNote Section (*.one).

Depending on your OneNote version, this option may be named OneNote 2010–2016 Section (*.one).
Select Export.
Choose a local folder and enter a name for the section.
Select Save.

Repeat these steps for every section that you want to move to Butterfly.

Exporting sections individually does not preserve the complete notebook hierarchy in one file. Each .one file is imported separately.

Do not export as PDF for a OneNote import

The OneNote export screen also offers formats such as PDF and XPS. These formats contain a rendered copy of the pages rather than their original OneNote structure.

Choose .one or .onepkg when you want Butterfly to convert editable content such as text, handwriting, images, tables, and attachments.

Use PDF import only when a visual, non-editable representation of the OneNote pages is sufficient.

Alternative: downloading a notebook from OneNote for the web

Microsoft also provides a notebook download through OneNote for the web.

This method is currently limited to notebooks stored in a personal OneDrive account. It is not available for notebooks stored in a work or school OneDrive account or in SharePoint.

Open OneNote for the web in a browser.
Find the notebook in the notebook list.
Right-click the notebook.
Select Export notebook.
Confirm the export.
Wait for the notebook to be downloaded.
Extract the downloaded ZIP archive.

The extracted notebook usually contains individual .one section files and an .onetoc2 table-of-contents file.

Butterfly cannot currently import the downloaded ZIP archive or the .onetoc2 file directly. Import the contained .one section files one at a time.

For a complete notebook import that preserves more of its hierarchy, prefer a .onepkg export from the Windows desktop application when that option is available.

Importing the file into Butterfly

Open Butterfly.
Open an existing Butterfly document or create a new one.
Open the Add dialog.
Select OneNote.
Choose the exported .one or .onepkg file.
Wait while Butterfly reads and converts the file.
Complete any dialogs concerning embedded XPS printouts.
Review the imported pages.

A .one file imports one section. A .onepkg file can contain multiple sections and section groups.

Butterfly creates a page for each supported OneNote page and attempts to preserve supported content, including:

Text and basic rich-text formatting
Handwriting and ink strokes
Images
Tables
Attached files
Printed document pages, when their XPS data can be converted to PDF

Section and section-group names are used as part of the imported Butterfly page paths.

Import limitations

OneNote and Butterfly use different document models. The importer therefore cannot guarantee a pixel-perfect or fully editable copy of every page.

After importing, check in particular:

Text positioning and wrapping
Fonts that are not installed on the current device
Complex formatting
Tables and nested content
Equations and uncommon OneNote objects
Embedded files
Page backgrounds
Printed documents
Internal links between OneNote pages
Password-protected or encrypted sections

Unsupported or unknown OneNote objects may be omitted. Parser warnings may also be stored with the imported document or page.

For large notebooks, importing can take some time. Notebooks containing many images, attachments, or printed documents also require more memory and disk space.

Printed documents and XPS files

OneNote may store inserted file printouts as XPS files. Butterfly displays these printouts as PDF elements, so the XPS data must first be converted to PDF.

Automatic conversion

On native desktop platforms, Butterfly first tries to run the following command:

xpstopdf

Automatic conversion only works when xpstopdf is installed and available through the system’s PATH.

When the command is missing or conversion fails, Butterfly opens the manual conversion workflow.

Automatic XPS conversion is unavailable in the web version of Butterfly.

Manual conversion

When Butterfly asks you to convert an XPS printout manually:

Select Convert manually.
Select Export XPS.
Save the exported .xps file somewhere you can find it.
Convert the XPS file to PDF using an external application.
Return to Butterfly.
Select Select converted PDF.
Select the corresponding PDF file.

Butterfly verifies that the selected file appears to be a valid PDF before continuing the import.

Canceling the file picker returns to the conversion dialog and does not cancel the complete OneNote import.

You can also choose:

Skip this file — omit only the current printout
Skip all XPS files — omit all remaining XPS printouts while importing the rest of the notebook
Export XPS again — save another copy of the current XPS file

Skipping an XPS printout does not skip the OneNote page or cancel the remaining notebook import. Only the affected printed document is omitted.

When several OneNote printout pages refer to the same XPS document, Butterfly reuses the converted PDF instead of asking for the same conversion repeatedly.

Troubleshooting

The OneNote option is missing in Butterfly

Make sure you are using a Butterfly version that includes OneNote import support. The importer accepts files ending in .one and .onepkg.

OneNote does not offer a `.onepkg` format

The available export formats depend on the OneNote edition and account configuration.

Export each section as a .one file instead. For personal OneDrive notebooks, you can also download the notebook through OneNote for the web, extract the archive, and import its .one files separately.

Butterfly asks for `xpstopdf`

The notebook contains one or more printed documents stored as XPS.

Install xpstopdf and ensure that it is available through PATH, or use the manual conversion workflow.

The converted PDF is rejected

Make sure you selected the actual converted PDF rather than the original XPS file or a renamed file.

Changing a filename from .xps to .pdf does not convert the document.

A printout is missing after import

The XPS conversion may have failed or the file may have been skipped. Import the notebook again and provide a converted PDF when Butterfly displays the conversion dialog.

Some content is missing or formatted differently

The object may not yet be supported by the OneNote parser or by Butterfly’s document model. Keep the original OneNote notebook and compare it with the imported result.

Acknowledgements

Butterfly’s OneNote import uses Dart and Flutter bindings based on onenote.rs, an open-source Microsoft OneNote file parser implemented in Rust.

Special thanks to Matthias Siemens and all contributors to onenote.rs for their work on understanding and implementing the OneNote file formats. Without their project, native OneNote file import in Butterfly would not be possible.

onenote.rs is an independent open-source project and is not affiliated with or endorsed by Microsoft.