Notion to Markdown Exporter

2.9.0 · active · verified Fri Apr 17

notion2md is a Python CLI tool designed to export Notion pages, databases, and blocks into markdown files. It leverages the Notion API client to fetch content and convert it into a standard markdown format. The current version is 2.9.0, and the project has an active, though irregular, release cadence with recent updates.

Common errors

```
ModuleNotFoundError: No module named 'notion2md'
```
cause The 'notion2md' package is not installed in your current Python environment.

fix Run `pip install notion2md` to install the package.
```
notion2md: command not found
```
cause The `notion2md` executable is not in your system's PATH, or the package was not installed with its entry points accessible.

fix Ensure `pip install notion2md` completed successfully. If using a virtual environment, ensure it is activated. You might need to add your Python scripts directory to your system's PATH.
```
Error during export: Command '['notion2md', 'invalid-id', '-o', 'output']' returned non-zero exit status 1. STDOUT: ... Error: Invalid id. Please provide a valid Notion block, page, or database ID.
```
cause The provided Notion ID is either incorrect, malformed, or does not exist, or the Notion integration does not have access to it.

fix Double-check the Notion ID for typos. Ensure it's a valid Block ID, Page ID, or Database ID. Verify that your Notion API token's integration has been explicitly granted access to the page/database in Notion.
```
Error: Authentication error: Invalid API token. STDOUT: ...
```
cause The `NOTION_TOKEN` environment variable is either missing, incorrect, or the token is expired/invalid.

fix Verify that `NOTION_TOKEN` is set correctly in your environment (e.g., `echo $NOTION_TOKEN`). Regenerate the token in Notion if necessary and update your environment variable.

Warnings

breaking Version 2.0.0 was a complete rewrite of the library, introducing significant breaking changes. Code written for versions prior to 2.0.0 will not be compatible.
Fix: Completely uninstall any old versions (`pip uninstall notion2md`) and reinstall (`pip install notion2md`). Review your code and CLI usage against the new documentation, as command-line arguments and internal APIs have changed.
gotcha The `NOTION_TOKEN` environment variable must be set correctly, and the associated Notion Integration must have the necessary read permissions for the specific pages or databases you are trying to export.
Fix: Verify your Notion API token is correct and set in your environment (e.g., `export NOTION_TOKEN='secret_...'`). In Notion, go to 'Settings & members' -> 'Integrations', find your integration, and ensure it has access to the pages/databases by inviting it to them.
gotcha notion2md relies on the Notion API. Changes in the official Notion API or its client libraries (e.g., `notion-client-py`) can lead to unexpected behavior or breakage in notion2md until the library is updated.
Fix: If you encounter unexpected errors, check the project's GitHub issues for recent reports and updates. Consider pinning `notion2md` to a specific version if you need stability in production and test updates carefully.
gotcha Not all Notion block types are perfectly supported or rendered in markdown. Complex blocks (e.g., sync blocks, advanced tables, some embedded content) might not export as expected or might be omitted.
Fix: Test your specific Notion content before relying on the export for complex layouts. Manually review exported markdown files for fidelity and be aware of limitations for certain Notion block types.

Install

pip install notion2md Install latest version

Imports

notion_to_markdown
```
from notion2md.exporter import notion_to_markdown
```
While primarily a CLI tool, this function allows programmatic export. However, CLI usage is more common.

Quickstart

The primary use case for notion2md is via its command-line interface. This quickstart demonstrates how to export a Notion page by setting the `NOTION_TOKEN` environment variable and executing the `notion2md` command with a page ID and an output directory. Ensure your Notion API token has the necessary read permissions.

import os
import subprocess

# Set your Notion API token as an environment variable
# Ensure the token has read access to the page/database you intend to export.
# Example: export NOTION_TOKEN="secret_YOUR_NOTION_TOKEN"
# For quick testing, you can set it directly (NOT recommended for production):
# os.environ['NOTION_TOKEN'] = 'secret_YOUR_NOTION_TOKEN'

# Replace with your actual Notion Page ID
NOTION_PAGE_ID = os.environ.get('NOTION_PAGE_ID', 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6')

if not os.environ.get('NOTION_TOKEN'):
    print("Error: NOTION_TOKEN environment variable is not set.")
    print("Please set it (e.g., export NOTION_TOKEN='secret_YOUR_TOKEN')")
else:
    print(f"Attempting to export Notion Page ID: {NOTION_PAGE_ID}...")
    try:
        # Example CLI usage: Export a Notion page to a local 'output' directory
        result = subprocess.run(
            ['notion2md', NOTION_PAGE_ID, '-o', 'output'],
            capture_output=True, text=True, check=True
        )
        print("Export successful!")
        print("STDOUT:", result.stdout)
        if result.stderr:
            print("STDERR:", result.stderr)
    except subprocess.CalledProcessError as e:
        print(f"Error during export: {e}")
        print("STDOUT:", e.stdout)
        print("STDERR:", e.stderr)
    except FileNotFoundError:
        print("Error: 'notion2md' command not found. Please ensure the package is installed and in your PATH.")

view raw JSON →