This guide covers both import routes, explains which one fits your setup, and lists the problems to watch for.
Why people move to Joplin
Phillips makes the case in plain terms. Joplin is free and open source. It organizes notes into notebooks, sub-notebooks and tags, and it supports Markdown, plugins and to-do items with deadlines. It can sync across devices through OneDrive, Dropbox, Nextcloud and other services, and it exports to Markdown, HTML and PDF. Joplin's own documentation confirms the export side. It lists HTML and PDF output for single notes, notebooks or the whole collection. It also offers its own JEX format, which keeps notes and metadata such as tags and timestamps intact and can be imported back into Joplin.
The guide is enthusiastic about Joplin, but it is still a how-to. OneNote's freeform canvas, ink and Microsoft 365 integration work very differently from a Markdown-based app. The real question is whether your notes will survive the move, so the rest of this guide focuses on that.
Summary: Joplin gives you more control over where your notes live and what format they're in. Whether it suits you depends on how much you use OneNote's freeform features.
Before you start: check your Joplin version
The guide gives the minimum versions each import method needs: Joplin 3.5.1 for the web route and 3.5.5 for the desktop route. Joplin's import documentation confirms both. Those numbers only tell you when the features arrived. They are not safe versions to run.
Joplin's OneNote importer had a serious bug. CVE-2026-22810 is a path traversal vulnerability in the importer which allows overwriting arbitrary files on disk. The OneNote converter does not sanitize the names of embedded files before writing them to disk. In practice, an attacker could create a malicious .one file that includes file names containing ../../, that are then interpreted as part of the target path when extracting attachments from the .one file.
Joplin's GitHub advisory, published May 15, 2026, lists affected versions 3.2.2 through 3.5.6 of the desktop app, with 3.5.7 as the patched release. The CVE record shows a severity of 8.2 (High) from GitHub as the assigning authority. NVD gave it a 7.3 HIGH base score. Both scores mark the exploit as requiring user interaction. An attacker needs you to import a booby-trapped file. Your own notebook exports are not the threat, but a .one file someone emails you could be.
What to do:
- Update Joplin desktop to 3.5.7 or later before importing anything. Recent changelog entries show 3.7-series releases shipping by September 2026, so a current download is well past the fix.
- Only import OneNote files you exported yourself or got from a source you trust.
Route 1: Download from OneDrive in your browser (several notebooks at once)
This is the faster option if your notebooks live in OneDrive. Joplin's documentation says it needs Joplin 3.5.1 or later and a notebook stored on OneDrive. It also warns that the method may fail for notebooks larger than about 2–4 GB. The import itself happens in Joplin's desktop app.
Steps (based on Phillips' walkthrough and Joplin's docs):
- Open OneDrive in a browser. You can also open OneNote for the web and click Show all notebooks, which takes you to OneDrive.
- Find the folder that holds your notebooks. Phillips suggests checking My Files > Documents > OneNote Notebooks first.
- If your notebooks are in different folders, right-click each one, choose Move to, and put them all in one folder.
- Open the folder to confirm everything is there, then click Download. OneDrive saves the folder as a ZIP file.
- In Joplin desktop, go to File > Import and choose the OneNote importer. Phillips' current build shows it as ONE - OneNote Notebook. Joplin's help page still calls it ZIP - OneNote Notebook, and the changelog records the label change from ZIP to ONE. It's the same importer under a different name.
- Select the ZIP file and click Open.
What success looks like: You get a new Joplin notebook named after the folder you downloaded, with each OneNote notebook nested inside it as a sub-notebook.
Account type matters. Phillips frames this route around personal OneDrive accounts. Microsoft's support page for its own browser-based "Export notebook" feature says it works only for notebooks on personal OneDrive. It does not work for notebooks on OneDrive for work or school or on SharePoint. Microsoft's export and the folder-download trick are separate workflows, and neither source fully explains how the folder-download method behaves in work or school tenants. If your notebooks are in a business or school account, the desktop route below is the more reliable choice. You may also want to check with your admin before moving company data into a personal app.
Route 2: Export from the OneNote Windows desktop app (one at a time)
This route needs Joplin 3.5.5 or later and the OneNote desktop app on Windows. Both Phillips and Joplin's documentation stress that this is not the same app as OneNote for Windows 10, the old Store app, which doesn't have this export menu. A quick check: if File shows an Export option, you have the right version.
To export a whole notebook:
- Select the notebook in OneNote.
- Go to File > Export and pick Notebook from the "Export Current" list.
- Choose OneNote Package (*.onepkg) as the format and click Export.
To export a single section:
- In the same Export menu, choose Section.
- Pick OneNote 2010–2016 Section (*.one/*.onex) and save the file.
Then import: In Joplin, go to File > Import, choose the OneNote importer, select the exported file, and click Open. Repeat for each notebook or section. You can't do them all in one batch the way the web route allows.
Platform note: Phillips and Joplin's current help page both say .onepkg files can only be imported when Joplin runs on Windows. On macOS or Linux, export individual sections instead. One thing doesn't match: Joplin's changelog for the 3.6.2 pre-release includes an entry about adding .onepkg support on Linux and macOS. That may mean the help page is out of date, but until the documentation is updated, plan on Windows for .onepkg files and use sections elsewhere.
Summary: Use the web route for bulk moves from personal OneDrive. Use the desktop route for very large notebooks, work or school accounts, or when you want to move things in small, controlled batches.
Troubleshooting common problems
Password-protected sections. In Phillips' testing, Joplin failed to import a password-protected section and reported an error with the section's data. That is one test result, not a documented limitation. Check protected sections separately, and consider removing the protection on a copy before you export.
Downloads that never finish. Microsoft notes that notebooks grow quickly once they contain embedded documents, scans, PDFs and audio or video, and it recommends having several gigabytes of free disk space before downloading. If a download stops because the disk filled up, free some space and start again.
A ZIP containing only "errors.txt". According to Microsoft, this means the export failed. Open the file in a text editor to see what went wrong.
"Notebook too large." Microsoft's fix is to split the notebook into smaller notebooks and export them separately. That also helps with Joplin's 2–4 GB limit on the web route. Or switch to the desktop route.
Formatting problems. Joplin's changelog shows steady work on the OneNote importer. Fixes include .onepkg imports that stopped after the first failed section, failures with some Unicode notebook titles, misplaced ink, PDF printouts imported as broken images, large attachments, and imported notes showing in a very small font, which was fixed in 3.7.18. If an import looked wrong in an older build, update and try it again.
Check your notes before you delete anything
When the import is done, open a sample of your notes, especially ones with tables, handwriting, drawings and attachments. Phillips also recommends keeping your original OneNote notebooks until you've confirmed everything important came across. Make a separate backup as well, so you have something to go back to if a note turns out to be missing months from now.
The bigger picture
Phillips presents this as the first step in moving away from Microsoft more broadly, with LibreOffice or ONLYOFFICE for Office documents and Thunderbird for email. That's a reasonable approach for anyone who wants their data in open formats, and doing it one app at a time is sensible. For this particular move, the advice is straightforward: update Joplin to 3.5.7 or later, confirm what kind of account your notebooks are in, pick the route that fits, and check the results before you delete anything.