How to Build Notion Import Pipeline From Obsidian Vault With Backlinks

You have an Obsidian vault with hundreds of interlinked notes and backlinks. Moving those notes to Notion without breaking the connections between them is difficult. Notion does not have a native import tool that preserves Obsidian backlinks. This article explains how to build a repeatable import pipeline that converts your Obsidian markdown files into Notion pages while keeping the backlink structure intact.

What the Obsidian-to-Notion Import Pipeline Does and What You Need

The pipeline converts a full Obsidian vault into a set of Notion pages. It preserves the content of each note and the backlinks that connect them. Obsidian uses wiki-style links like [[Note Name]] for internal references. Notion uses page mentions that require a page ID. The pipeline must translate each wiki link into a corresponding Notion page mention.

Before starting, you need a Notion integration token, a Notion database where pages will be created, and a Python environment with the requests and markdown libraries. You also need your Obsidian vault exported as plain markdown files. Obsidian stores notes in a folder of .md files by default. If your vault uses the Obsidian Sync service, download the vault to a local folder first.

How Backlinks Work in Obsidian vs Notion

In Obsidian, a backlink is a two-way connection. When you write [[Note B]] in Note A, both notes show a link to the other in the backlinks pane. Notion does not have an automatic backlink pane. Instead, you create a mention by typing @ and selecting a page. The pipeline will create these mentions in the imported notes so that clicking a mention opens the related page.

Limitations of Native Notion Import

Notion’s built-in Markdown import converts .md files to pages. It does not parse wiki links. It treats [[Note Name]] as plain text. This means all your Obsidian cross-references become unlinked text. The pipeline in this article solves that problem by converting each wiki link into a Notion mention during the import process.

Steps to Build the Import Pipeline

The pipeline has three stages: export the Obsidian vault, run a Python script that converts each file to a Notion page with mentions, and verify the backlinks in Notion. The script handles the conversion and API calls automatically.

1. Export your Obsidian vault as plain markdown files
   Open Obsidian. Click Settings > Files & Links. Confirm that the “Use [[Wikilinks]]” toggle is enabled. This ensures your links use the wiki format. Navigate to your vault folder. Copy the entire folder to a new location outside Obsidian. This folder will be the input for the pipeline.
2. Create a Notion integration and get your API token
   Go to https://www.notion.so/my-integrations. Click “New integration.” Give it a name like “Obsidian Import.” Select the workspace where you will import the pages. Click Submit. Copy the Internal Integration Secret token. You will use this token in the Python script.
3. Share a Notion database with the integration
   In Notion, create a new database page. This database will hold all imported pages. Click Share in the top right. Add your integration by typing its name. Select the integration and click Invite. The integration now has permission to create pages in this database.
4. Install Python and required libraries
   Open a terminal or command prompt. Run pip install requests markdown. If you do not have Python installed, download it from python.org and install version 3.8 or later.
5. Write the conversion script
   Create a new file named obsidian_to_notion.py. The script does the following: (a) reads every .md file in the input folder, (b) extracts the note title from the filename, (c) parses the markdown content, (d) finds all [[wiki links]] using regex \[\[([^\]]+)\]\], (e) replaces each wiki link with a placeholder that includes the target page title, (f) sends each note to the Notion API as a new page in the database, (g) stores the Notion page ID for each imported note in a dictionary, (h) after all pages are created, updates each page to replace the placeholders with actual Notion mentions using the stored page IDs. The script must handle duplicate note titles by appending a suffix to the page title.
6. Run the script
   In the terminal, run python obsidian_to_notion.py. The script will process each file and display progress messages. Wait for the script to finish. This may take several minutes for large vaults.
7. Verify backlinks in Notion
   Open the Notion database where pages were created. Click any page. Look for text that shows a mention (a blue link with the page icon). Click the mention. The linked page should open. If the mention shows plain text instead of a link, the script did not find the target page ID. Check the console output for errors about missing page titles.

If the Pipeline Fails to Create Mentions

Wiki link target does not exist as a page title

If a wiki link points to a note that was not exported or has a different title, the script will leave it as plain text. To fix this, ensure every linked note is present in the input folder. Use a tool like grep to find all wiki links and compare them to the list of filenames.

Notion API rate limit reached

The Notion API allows 3 requests per second per integration. If your vault has more than 300 notes, the script may hit the rate limit. Add a time.sleep(0.35) call between API requests in the script to stay under the limit.

Page mentions show as @Untitled

This happens when the script creates a page with an empty title. Verify that your markdown files have a title on the first line. The script should use the filename without the .md extension as the default title. If the file starts with a # heading, the script can use that instead.

Database not shared with the integration

If the script returns a 403 error, the integration does not have access to the target database. Go to the database in Notion, click Share, and confirm your integration is listed. If not, repeat step 3.

Obsidian Vault Export vs Notion Import Methods Compared

Item	Native Notion Markdown Import	Custom Pipeline with API
Backlink preservation	No – wiki links become plain text	Yes – converts to Notion mentions
Setup time	5 minutes	1–2 hours
Automation	Manual one-time	Repeatable with script
Handles large vaults	Yes, but no backlinks	Yes, with rate limiting
Requires coding	No	Yes, basic Python

The custom pipeline requires more upfront work. It is the only method that keeps your Obsidian backlinks functional in Notion.

You can now import an entire Obsidian vault into Notion while preserving every backlink as a clickable mention. The script handles the conversion automatically after you set up the integration and database. For future imports, run the script again on the same folder to update existing pages or add new ones. To improve the pipeline further, add a feature that detects when a wiki link target does not exist and creates a placeholder page with that title in the same database.