Notion to Obsidian Migration: API vs HTML Import Checklist

The safest way to move from Notion to Obsidian depends on what your workspace contains. Use the official Notion API import when databases and formulas matter. Use the Notion HTML file import when you want a token-free, offline migration and can rebuild database views yourself.

Do not treat the migration as a file-copy exercise. First decide which workflows must survive: linked notes, project records, daily planning, recurring tasks, meetings, or database views. Then import into a test vault, verify the important workflows, and keep Notion available until the new vault passes the checklist at the end of this guide.

Quick decision: API or HTML import?

Your situation	Choose	What it preserves	Main trade-off
Databases, properties, and formulas are central	Notion (API)	Pages, database entries, properties, and formulas converted to Markdown and Bases	Requires a Notion integration token, page access, and an internet connection
You want a token-free or offline process	Notion (.zip)	Pages, attachments, hierarchy, and links from an HTML export	Database views and database structure do not come across as live Bases
You only need a small set of notes	API import with access limited to those pages, or a page-level HTML export	The selected notes and their available attachments	Links to content outside the selected scope need review
You need real-time collaboration and permissions	Keep that workflow in Notion or pair Obsidian with a team tool	The knowledge context can still move to Obsidian	Obsidian is not a drop-in replacement for shared Notion workspaces

This table reflects the current Obsidian Importer documentation. The API importer is described as new, so review its limitations before a large migration. In particular, only the primary view of each database is imported, linked data sources are not imported, and some Notion functions are not converted.

Before you migrate

Create a short inventory. Mark each item as must preserve, rebuild, or retire.

• Notes and nested pages that you still use.
• Internal links, backlinks, and important attachments.
• Databases, properties, relations, rollups, formulas, and views.
• Daily notes, recurring tasks, project status, and meeting follow-up.
• Shared pages, comments, permissions, automations, and integrations.
• The backup and sync path for the new local vault.

Use the inventory to choose the import path. A large database-heavy workspace needs a different plan from a folder of meeting notes. If you want a broader comparison before moving, read Obsidian vs Notion for productivity.

Create a safe test boundary

1. Keep the original Notion workspace unchanged.
2. Create a new, empty Obsidian test vault.
3. Export or import a representative sample first: one ordinary page, one nested page, one linked page, one attachment, and one database.
4. Record what arrived and what needs rebuilding.
5. Repeat in the destination vault only after the sample passes.

The test is not a promise that every workspace behaves the same way. It exposes the parts of your workspace that need a new design before you abandon the old one.

Option 1: Import through the Notion API

Use this path when databases and their properties are important. The official Importer plugin converts Notion databases to folders with a .base file and converts formulas where Obsidian supports an equivalent.

Prepare the Notion integration

1. Open the Notion integrations page.
2. Create an internal integration for the workspace.
3. Copy its internal integration secret into a secure password manager.
4. Give the integration access to the pages and databases that you want to import.

Do not paste a token into an article, shell history, issue, or shared note. The token grants access to the content that you share with the integration.

Run the API import

1. Open Settings → Community plugins in Obsidian.
2. Install and enable the official Importer plugin.
3. Open Importer from the command palette or its ribbon icon.
4. Select Notion (API) as the file format.
5. Paste the integration secret and select Load.
6. Choose the pages and databases to import.
7. Review the import options and start the import.

Large workspaces can take time because the Notion API has rate limits. Import only after you have granted access to the correct parent pages. A current Importer issue about missing pages shows why access scope and page hierarchy deserve a check when the selection list looks incomplete.

API limitations to plan for

The official documentation identifies these limits:

• Only the primary view for each database is imported.
• Linked data sources are not imported.
• People functions such as name() and email() are not converted.
• Text functions such as style() and unstyle() are not converted.
• Formulas that have no suitable Obsidian function need manual review.

Treat the imported .base file as a starting view, not proof that every Notion view survived. Check relations, formulas, filters, and the records that your daily work depends on.

Option 2: Import a Notion HTML export

Use file import when you want a token-free path or when your workspace is mostly pages and attachments. Obsidian recommends an HTML export for this route because a Notion Markdown export omits important data.

Export from Notion

1. Open Settings → Workspace → General in Notion.
2. Select Export all workspace content.
3. Choose HTML as the export format.
4. Select Include everything.
5. Enable Create folders for subpages.
6. Request or download the .zip export.

The Notion export documentation confirms that workspace exports can include HTML, Markdown, CSV files, and uploaded assets. It also notes that database views and some workspace content do not export as a fully recreatable workspace.

Import the .zip file

1. Open the official Importer plugin in Obsidian.
2. Select Notion (.zip).
3. Choose the exported file.
4. Select an output folder.
5. Enable Save parent pages in subfolders when you want to retain the page hierarchy.
6. Import the full export when internal links across the workspace matter.

This route brings pages and assets into a local Markdown vault, but it does not preserve Notion databases as live database views. Do not install a large plugin stack before you know which workflows need rebuilding.

Rebuild only the workflows you still use

An imported archive is not yet a working system. Start with the smallest replacement for each active workflow.

Notion workflow	Obsidian starting point	Verify before closing Notion
Documents and reference pages	Markdown notes, folders, search, and internal links	Open five important pages and follow their links
Database of projects or tasks	API-imported Bases, or properties plus a scoped view	Filter by status, due date, and one real project
Daily planning	Core Daily notes plus a template	Create a note for today and confirm the template and folder
Recurring work	Tasks plugin or a simple recurring-note convention	Create, query, and complete one recurring task
Meetings and contacts	Meeting notes linked to projects and people	Find one action from its meeting and project context
Shared approvals and comments	Keep the collaboration workflow in Notion or another team tool	Confirm who still needs access and notifications

For a prepared local-first system, Obsibrain’s task management, daily planning, Smart Projects, and periodic reviews cover the parts of a migration that usually need more than a folder of Markdown files. Use those links after you identify the workflow gap; a ready-made system is useful when wiring the replacement is the problem.

If you prefer to build the system yourself, start with the PARA method in Obsidian or a second-brain setup. Add a database view or community plugin only when a real question remains unanswered.

Migration acceptance checklist

Run this check before you make Notion read-only or cancel a paid plan.

Content and links

• Every must-preserve page exists in the new vault.
• Nested pages are in the expected folder or link structure.
• Important internal links open the intended notes.
• Important images, PDFs, and other attachments open locally.
• Search finds the pages and properties that you use weekly.

Data and views

• Database rows that matter to current work exist.
• Properties have the expected names and types.
• Relations point to the right notes or have a documented fallback.
• Formulas and rollups have a tested replacement or a recorded limitation.
• The primary project, task, or contact view answers its real question.

Daily use and exit

• A new daily note lands in the right folder with the right template.
• One task can move from capture to completion without duplication.
• One meeting action stays connected to its source context.
• The vault has a backup and a multi-device plan.
• Notion remains available until the checklist passes on ordinary work.

Troubleshooting guide

Symptom	First check	Practical response
API import shows no page or database	Integration access and parent-page sharing	Share the correct parent page, reload the selection, and test a small scope
A database arrives without the expected view	Primary-view and linked-data-source limits	Rebuild the missing view in Bases, or keep that workflow in Notion
A formula does not behave the same way	Whether Obsidian has an equivalent function	Preserve the result as a property and document the original formula
HTML import contains raw or missing formatting	Export format and attachment paths	Use HTML, keep the export intact, and repair the highest-value notes first
The vault feels cluttered after import	Whether the migration copied an archive instead of a workflow	Archive old material and build around the notes you still use

The Obsidian Importer issue tracker is the right place to check current edge cases. Community reports describe problems with incomplete page trees, permissions, old Notion data structures, and large-workspace pagination. Treat those reports as observed cases, not guarantees about your own workspace.

Final recommendation

Choose API import for a database-heavy workspace. Choose HTML import for a token-free, page-first migration. In both cases, use a test vault, preserve the original export, and rebuild only the workflows that still matter.

The goal is not to reproduce every Notion view. The goal is a local, connected system that helps you capture ideas, manage projects, plan days, and review commitments. If the setup work is the main obstacle, use a ready-made Obsidian system; if collaboration is the main requirement, keep that part in a tool designed for teams.

Sources and further reading

• Obsidian: Import from Notion
• Notion: Export your content
• Obsidian Importer issue tracker
• Obsidian Importer issue: missing pages or databases