{"id":9985,"library":"notion2md","title":"Notion to Markdown Exporter","description":"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.","status":"active","version":"2.9.0","language":"en","source_language":"en","source_url":"https://github.com/echo724/notion2md","tags":["notion","markdown","exporter","cli","documentation"],"install":[{"cmd":"pip install notion2md","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"While primarily a CLI tool, this function allows programmatic export. However, CLI usage is more common.","symbol":"notion_to_markdown","correct":"from notion2md.exporter import notion_to_markdown"}],"quickstart":{"code":"import os\nimport subprocess\n\n# Set your Notion API token as an environment variable\n# Ensure the token has read access to the page/database you intend to export.\n# Example: export NOTION_TOKEN=\"secret_YOUR_NOTION_TOKEN\"\n# For quick testing, you can set it directly (NOT recommended for production):\n# os.environ['NOTION_TOKEN'] = 'secret_YOUR_NOTION_TOKEN'\n\n# Replace with your actual Notion Page ID\nNOTION_PAGE_ID = os.environ.get('NOTION_PAGE_ID', 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6')\n\nif not os.environ.get('NOTION_TOKEN'):\n    print(\"Error: NOTION_TOKEN environment variable is not set.\")\n    print(\"Please set it (e.g., export NOTION_TOKEN='secret_YOUR_TOKEN')\")\nelse:\n    print(f\"Attempting to export Notion Page ID: {NOTION_PAGE_ID}...\")\n    try:\n        # Example CLI usage: Export a Notion page to a local 'output' directory\n        result = subprocess.run(\n            ['notion2md', NOTION_PAGE_ID, '-o', 'output'],\n            capture_output=True, text=True, check=True\n        )\n        print(\"Export successful!\")\n        print(\"STDOUT:\", result.stdout)\n        if result.stderr:\n            print(\"STDERR:\", result.stderr)\n    except subprocess.CalledProcessError as e:\n        print(f\"Error during export: {e}\")\n        print(\"STDOUT:\", e.stdout)\n        print(\"STDERR:\", e.stderr)\n    except FileNotFoundError:\n        print(\"Error: 'notion2md' command not found. Please ensure the package is installed and in your PATH.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install notion2md` to install the package.","cause":"The 'notion2md' package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'notion2md'"},{"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.","cause":"The `notion2md` executable is not in your system's PATH, or the package was not installed with its entry points accessible.","error":"notion2md: command not found"},{"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.","cause":"The provided Notion ID is either incorrect, malformed, or does not exist, or the Notion integration does not have access to it.","error":"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."},{"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.","cause":"The `NOTION_TOKEN` environment variable is either missing, incorrect, or the token is expired/invalid.","error":"Error: Authentication error: Invalid API token. STDOUT: ..."}]}