How to Migrate from OneNote to Joplin: A Privacy-Focused Transition Guide

In this article

1. Architecture Comparison: OneNote Canvas vs. Joplin Markdown
2. Pre-Migration Audit: Organizing Content and Handling Edge Cases
3. Exporting from OneNote: Supported Formats and Conversion Paths
4. The Conversion Pipeline
5. Importing Content into Joplin
6. Configuring Cloud Synchronization
7. Joplin End-to-End Encryption Setup
8. Step 1: Generate the Master Key on Desktop
9. Step 2: Encrypt the Local Database
10. Step 3: Pair Secondary Devices and Enter the Master Key
11. Post-Migration Validation: Resolving Incompatible Layouts

Moving your personal and technical documentation out of proprietary ecosystems gives you direct ownership of your data. For many users seeking an open source OneNote alternative, Joplin represents a natural destination. It provides local-first data storage, cross-platform availability, and client-side encryption.

However, an export from OneNote to Joplin is not a direct drag-and-drop process. The two applications rely on fundamentally different data models. Understanding these underlying architectural differences is essential to plan a clean export pipeline, preserve your notebook organization, and configure private synchronization across all your devices.

Architecture Comparison: OneNote Canvas vs. Joplin Markdown

The primary hurdle when you migrate from OneNote to Joplin is structural. OneNote utilizes an absolute-position, free-form canvas engine. Users can click anywhere on a page to generate an independent text box, drop an image, embed an audio file, or write freehand digital ink. Elements sit on an unbounded 2D plane with distinct spatial coordinates.

Joplin, by contrast, operates on a structured, linear CommonMark/Markdown text model. Note content flows sequentially from top to bottom. Joplin stores notes, tags, folder relationships, and metadata inside an internal SQLite database, while attachments, images, and embedded media are managed as separate resource files referenced by cryptographic identifiers.

Feature	Microsoft OneNote	Joplin
Content Layout	Unbounded 2D free-form canvas	Linear CommonMark / Markdown
Data Storage	Proprietary cloud or binary sections (.one)	Local SQLite database and resource files
Formatting Portability	Tightly coupled to Microsoft ecosystem	Standard plain text (portable Markdown)
Encryption Model	Section-level passwords (server-dependent)	Zero-knowledge End-to-End Encryption (E2EE)
Digital Ink	Native vector ink layers	Static raster images (attachments)

Because Markdown does not support absolute positioning, independent text boxes placed side by side on a OneNote canvas must be linearized into sequential paragraphs. Understanding this structural transformation prevents surprises when reviewing converted files.

Pre-Migration Audit: Organizing Content and Handling Edge Cases

Performing an audit on your OneNote notebooks before triggering any export ensures you avoid broken layouts and missing data during import.

• Consolidate Floating Text Boxes: If a OneNote page relies heavily on text boxes placed horizontally across the screen, reorder them vertically in logical reading order before exporting.
• Review Hand-Drawn Ink: Joplin cannot natively maintain editable vector ink strokes. Digital ink, sketches, and handwritten annotations must be converted into standard image attachments during conversion. If you have critical handwritten notes, verify that they are saved or rasterized as clear images.
• Check Nested Subpages: OneNote permits multiple levels of page nesting (pages and subpages). Joplin represents hierarchy through nested notebooks and sub-notebooks. Decide whether you want subpages turned into individual sub-notebooks or merged into standalone notes.
• Audit Large Attachments: Embedded files like PDFs, presentations, and audio recordings will become local attachments in Joplin. If you are mindful of device storage or sync overhead, remove obsolete files before beginning the transition. If you are handling sensitive local documentation alongside this setup, consider pairing your broader workflow with local self-hosted tools such as those covered in our guide on how to set up Paperless-ngx for document management.

Exporting from OneNote: Supported Formats and Conversion Paths

Joplin does not natively parse proprietary OneNote .one or .onetoc2 files directly from disk without conversion. Consequently, you must establish an intermediate conversion pipeline.

The available export capabilities depend significantly on your operating environment:

• OneNote Desktop (Windows): The desktop client on Windows has historically provided broader export and local automation capabilities compared to mobile or web editions. Many community conversion utilities rely on Windows desktop components to extract notebook hierarchies.
• OneNote for Mac and Web: These environments generally provide more limited local export controls for notebook and section files. Migrating from these platforms often involves syncing notebooks across to a desktop client with fuller export tooling or relying on third-party conversion tools that connect via cloud APIs.

The Conversion Pipeline

To prepare your notebooks for Joplin, the migration pipeline must carry out three steps:

1. Extraction: Pulling the hierarchy (Notebooks > Section Groups > Sections > Pages > Subpages) and raw HTML/text from the OneNote container.
2. Parsing and Normalization: Converting proprietary HTML and canvas layouts into clean, standard CommonMark formatting. Tables must become Markdown tables, and embedded media must be extracted into an accompanying asset directory.
3. Packaging: Outputting the result into a format Joplin can import, such as a structured directory of Markdown files with frontmatter, or an intermediary archive format.

When selecting a community-developed OneNote to Joplin migration tool or open-source conversion script, prioritize tools that write raw Markdown files accompanied by an assets folder. This approach guarantees that even if an import issue occurs, your raw data remains fully accessible in open plain text.

Importing Content into Joplin

Once your intermediate files are generated, the import process takes place directly inside the Joplin desktop application.

1. Create a Staging Notebook: Before importing your full collection, create an empty staging notebook in Joplin. Importing into a staging container keeps your existing notes organized and isolates incoming files for quality checks.
2. Trigger the File Import: Open Joplin and locate the import option within the application menus. Choose the format corresponding to your intermediate output, such as standard Markdown directories or another format supported by your chosen conversion script.
3. Verify Folder Hierarchies: Inspect how the converter handled your sections. If you used a directory-based import, ensure Joplin mirrored your folder tree accurately into corresponding sub-notebooks.
4. Inspect Attachments: Open notes that previously contained embedded PDFs, images, or audio clips. Confirm that the internal resource identifiers properly display the media in Joplin’s split-view Markdown previewer.

Configuring Cloud Synchronization

Joplin operates on an offline-first architecture, meaning all changes are committed locally before syncing. Once your imported notes are inside Joplin, you can establish synchronization across mobile and desktop clients using a storage backend of your choice.

Supported synchronization targets generally include:

• Joplin Cloud: A dedicated hosted synchronization service designed specifically for Joplin data.
• Nextcloud / WebDAV: A private, self-hosted option that gives you complete operational control over your storage server.
• Standard Cloud Storage: Supported third-party cloud providers, such as Dropbox or OneDrive.
• File System Sync: Local file system targets, which allow you to pair Joplin with custom synchronization daemons. If you prefer decentralized local syncing, you can read our walkthrough on how to set up Syncthing for private file sync.

To configure your target, open Joplin’s application settings or preferences, navigate to the synchronization section, select your synchronization target, and enter the required connection parameters. Trigger an initial sync from your primary computer and allow the data to upload completely before configuring secondary devices.

Joplin End-to-End Encryption Setup

A central advantage of moving to Joplin is the ability to protect your entire database with zero-knowledge encryption. Joplin end to end encryption setup (E2EE) ensures that notes, notebook names, tags, and media attachments are encrypted client-side using a user-managed master key prior to transmission.

Even if you sync via a standard third-party cloud provider, the host cannot read the plaintext contents of your notes.

Step 1: Generate the Master Key on Desktop

1. Open Joplin’s settings or preferences and locate the encryption section.
2. Enable end-to-end encryption.
3. When prompted, define a robust master password. This password derives the cryptographic key that decrypts your database. Because Joplin does not store your password on any central server, recovery is impossible if you lose this passphrase.
4. Allow Joplin to generate the master key and designate it as active.

Step 2: Encrypt the Local Database

Enabling E2EE does not instantaneously upload your data. Joplin must encrypt local notes, tags, and resources individually. Trigger a manual synchronization cycle and monitor the status screen. Depending on the size of your imported media and attachments, the initial encryption and upload process will take some time.

Step 3: Pair Secondary Devices and Enter the Master Key

1. Install Joplin on your secondary desktop or mobile device.
2. Navigate to the synchronization settings and configure the exact same sync target used on your primary computer.
3. Run an initial sync. The application will detect the encrypted sync target and notify you that an encrypted master key is present.
4. Open the encryption settings on the secondary device, locate the key, and enter the password you created in Step 1.
5. Trigger a sync cycle. The secondary device will decrypt your notes locally and reconstruct your notebook hierarchy.

Post-Migration Validation: Resolving Incompatible Layouts

After your initial import and synchronization cycles complete, perform a structured audit across your notes to resolve typical syntax and layout discrepancies:

• Complex Table Spacing: OneNote allows nested tables and cells containing line breaks or embedded images. Markdown tables require uniform row-and-column formatting. If a table broke during extraction, convert the cell contents into linear bulleted lists or standard Markdown blocks.
• Internal Note Links: Links between OneNote pages often rely on proprietary URLs (e.g., onenote:... links). Once imported into Joplin, these links will fail to navigate internally. Replace them by generating internal Markdown links between notes directly within Joplin and updating the referencing text.
• Orphaned Canvas Fragments: Small text snippets, annotations, or dates placed off to the side of the main OneNote canvas may appear as isolated paragraphs at the very bottom of imported Markdown notes. Review high-priority notes and reposition these fragments into their proper context.

Completing this conversion gives you full custody of your notes in an open format, backed by strong client-side encryption and free from proprietary platform dependencies.