Why notion2obsidian?

⚡

Lightning Fast

Migrate your entire workspace in seconds. Batch processing with concurrent operations handles thousands of files effortlessly.

📦

Zero-Friction Setup

Extract and migrate zip files in one command. Preview changes with dry-run mode. No manual extraction, no backups cluttering your workspace.

🔗

Perfect Migration

Smart link conversion, auto-tagging, frontmatter generation, callout conversion, database processing with Dataview support, and duplicate handling. Everything works in Obsidian from day one.

Who is this for?

🔄

Notion Refugees

Making the switch to Obsidian for better performance, offline access, or local-first control? Migrate your entire workspace in seconds.

🧠

Second Brain Builders

Years of notes in Notion but want Obsidian's graph view, backlinks, and plugin ecosystem? Keep your structure intact during migration.

⚙️

Automation Enthusiasts

Need a scriptable, CLI-based migration that you can run on multiple exports or integrate into workflows? Built for the command line.

What it does

🧹

Cleans filenames

Removes 32-character Notion IDs from files and directories

My Document 2d6fa1e585714845.md

→

My Document.md

📝

Adds frontmatter

Generates YAML metadata including title, tags (auto-generated from folder structure), and Notion IDs

---
title: "My Document"
tags: [projects, work]
notion-alias:
  - "My Document 2d6fa1e585714845"
notion-id: "2d6fa1e585714845be81f7d5ca30194a"
published: false
---

🔗

Converts links

Transforms markdown links to Obsidian wiki links

[text](file.md)

→

[[file|text]]

🎯

Handles duplicates

Uses folder context to disambiguate files with identical names

folder: "Work/Projects"

📦

Organizes attachments

Moves markdown files into their attachment folders and simplifies image paths

![Image](My%20Doc%202d6fa1e5/img.png)

→

![Image](img.png)

💬

Converts callouts

Transforms Notion callouts with icons to Obsidian format

→

> [!note] 📘 Content

📊

Organizes databases

Creates clean CSV files with Dataview-compatible index pages showing all records

Default structure:
Tasks.csv (clean file)
Tasks_Index.md (Dataview query)
Tasks/_data/ (individual pages)

📦 Requires: Dataview plugin

Get Started ~90 seconds

Why Bun? This tool is built with Bun, a modern JavaScript runtime that's significantly faster than Node.js. Bun handles thousands of files in seconds and provides native TypeScript support. Installing Bun takes just one command and won't interfere with your existing Node.js setup.

Install Bun runtime

Bun is a fast JavaScript runtime. If you already have it, skip to step 2.

curl -fsSL https://bun.sh/install | bash

Install notion2obsidian

Install the tool globally to use it anywhere.

bun install -g notion2obsidian

Export from Notion

In Notion: Settings & Members → Export → Export all workspace content → Markdown & CSV

Run the migration

Point to your downloaded zip file with optional output directory.

notion2obsidian Export-*.zip ~/Documents/Obsidian

Preview first: add --dry-run

Open in Obsidian & Install Dataview

Create a new vault and install the Dataview plugin for database features.

Common Questions

? Will this modify my original Notion export?

Your original .zip file is never modified. The tool extracts it to a temporary location, moves files to the output directory (specified with -o or created next to the zip), then cleans up the temp folder. The migration modifies only the output directory. Use --dry-run to preview changes before committing.

? What if I have duplicate filenames?

The tool handles duplicates in two ways:

1. Files in different folders: Folder context added to frontmatter

Work/Projects/README.md:
---
folder: "Work/Projects"
---

Personal/Notes/README.md:
---
folder: "Personal/Notes"
---

2. Naming conflicts: Sequential suffixes (-1, -2, etc.)

Untitled 888cfab6.md  →  Untitled-1.md
Untitled 85f75240.md  →  Untitled-2.md
Untitled 985c88c5.md  →  Untitled-3.md

? Do I need to extract the zip file first?

No! Just point notion2obsidian at the .zip file and it will extract and migrate in one step.

? What about images and attachments?

All images, PDFs, and other attachments are preserved and organized. Files with attachments are moved into their attachment folders for better organization:

Before:

My Document.md
My Document 2d6fa1e5/
  image1.png
  image2.png

After:

My Document/
  My Document.md  ← moved inside
  image1.png
  image2.png

Image paths simplified from My%20Document/image.png to just image.png

? Do I need any Obsidian plugins?

For database features: Install the Dataview plugin to view and query your Notion databases. Without it, database index pages will only show raw query code instead of interactive tables.

For cover images (with --enrich): Install the Obsidian Banners plugin to display cover images enriched from Notion. Covers are downloaded to _banners/ folder.

For icons (with --enrich): Install the Iconize plugin to display emoji and image icons enriched from Notion. Emoji icons work immediately; image icons are downloaded and configured automatically.

Install in Obsidian: Settings → Community plugins → Browse → Search plugin name → Install & Enable

? How do I enrich my vault with Notion API metadata?

The --enrich flag adds creation dates, last edited times, public URLs, and downloads cover images from Notion. Here's how to set it up:

Step 1: Get your Notion Integration Token

Go to notion.so/my-integrations
Click "New integration" and give it a name (e.g., "Obsidian Migration")
Under "Capabilities", enable "Read content"
Copy the "Internal Integration Secret" (starts with ntn_ for new tokens)

Step 2: Grant access to your pages

Go to notion.so/profile/integrations/internal/
Select your integration
Choose pages to share (select both private and shared pages you want to enrich)

💡 Note: Integration must be internal (not public)

Step 3: Set environment variable

Temporary (current session only):

export NOTION_TOKEN="ntn_xxx"

Permanent (add to shell config):

# For bash
echo 'export NOTION_TOKEN="ntn_xxx"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export NOTION_TOKEN="ntn_xxx"' >> ~/.zshrc
source ~/.zshrc

Step 4: Run enrichment

cd ~/Documents/Obsidian/MyVault
notion2obsidian . --enrich

? Can I undo the migration?

Yes. Your original .zip file is never touched. Simply delete the output directory and run the migration again to start fresh. The tool automatically cleans up temporary files, so you only need to manage the output directory.