Ultimate Notion is the ultimate Python client for Notion! It allows you to access, create and change your Notion databases and pages in the most convenient and pythonic way.

CI/CD
Package
Details

• 🗂️ CRUD operations — Create, read, update, and delete Notion pages and databases.
• 🐍 Pythonic API — Clean, intuitive interfaces that feel natural in Python.
• 🔒 Token-based authentication — Secure access using Notion integration tokens.
• 🔎 Rich querying capabilities — Support for filters, sorting, pagination, and searching.
• 🧩 Integration with notion-sdk-py — Built atop the official client, enhancing functionality.
• 🚀 One-step setup — Getting up to speed with a simple setup guide.

👉 Want to learn more? Check out the full feature breakdown.

Install the most recent release using PyPI with:

pip install ultimate-notion

or to install all additional dependencies, use:

pip install 'ultimate-notion[all]'

To install the latest (potentially unstable) version directly from the main branch on GitHub:

pip install git+https://github.com/ultimate-notion/ultimate-notion.git@main

or with all optional dependencies:

pip install 'ultimate-notion[all] @ git+https://github.com/ultimate-notion/ultimate-notion.git@main'

Make sure you have set the environment variable NOTION_TOKEN to your Notion integration token. Then it's as simple as:

import ultimate_notion as uno

PAGE_TITLE = 'Getting Started'

with uno.Session() as notion:
    page = notion.search_page(PAGE_TITLE).item()
    page.show()

# Alternatively, without a context manager:
notion = uno.Session()
page = notion.search_page(PAGE_TITLE).item()
page.show()
notion.close()

Check out the official Ultimate Notion documentation for more details. Especially the page about creating a Notion integration to get the token.

If you are stuck with a problem and need help or just want to brag about what you did, the Discussion area is the right place for you. Here, you can ask questions, provide suggesions and discuss with other users.

After having cloned this repository:

1. make sure hatch is installed globally, e.g. pipx install hatch,
2. make sure pre-commit is installed globally, e.g. with pipx install pre-commit,

and then you are already set up to start hacking. Use hatch run test to run the unit tests or hatch run vcr-only to run the offline unit tests using VCR.py. Regenerate the cassettes with hatch run vcr-rewrite. Check out the environment setup of hatch in pyproject.toml for many more commands.

If you are using VS Code, it's quite convenient to create a file .vscode/.env with

NOTION_TOKEN=TOKEN_TO_YOUR_TEST_NOTION_ACCOUNT
ULTIMATE_NOTION_CONFIG=/path/to/repo/.ultimate-notion/config.toml

Check out this page about contributing for more details.

Ultimate Notion is distributed under the terms of the MIT license. Ultimate Notion is built on top of notion-sdk-py. To start this project off a lot of inspiration and code was taken from notional and the overall project setup from hatch. The documentation is made with Material for MkDocs and is hosted on GitHub Pages.