Ultimate Notion is the ultimate Python client for Notion!
| CI/CD |      |
| Package |     |
| Details |        |
✨ Features
- 🐍 Pythonic API — Clean, intuitive Python interfaces with robust type annotations.
- 🗂️ CRUD operations — Create, read, update, and delete Notion pages, databases, and blocks.
- 🔎 Rich querying capabilities — Support for filters, sorting, pagination, and searching.
- 🪄 Flexible exports — Convert Notion pages to Markdown, HTML, and databases to pandas, Polars.
- ⬆️ File upload support — Easily upload and manage files in Notion pages and databases.
- 🧩 Built atop notion-sdk-py — Enhancing the functionality of the popular low-level client.
- 💯 100% feature parity — Full compatibility with all notion-sdk-py capabilities and more.
- 🖥️ Command line interface — Convenient CLI for quick operations and automation scripts.
- 🔒 Token-based authentication — Secure access using Notion integration tokens.
- 🚀 One-step setup — Getting up to speed with a simple setup guide.
- 📜 MIT licensed — Released under the permissive MIT license for maximum flexibility.
👉 Want to learn more? Explore the full feature breakdown.
📦 Installation
Install the most recent release using PyPI with:
pip install ultimate-notion
or to install all additional dependencies, use:
pip install 'ultimate-notion[all]'
🧪 Installing the Development Version
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'
🚀 Usage
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.
💬 Getting help
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.
🤝 Contributing
After having cloned this repository:
- make sure hatch is installed globally, e.g.
pipx install hatch, - 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.
📄 License & Credits
Ultimate Notion is released under the terms of the MIT license. It is built on top of notion-sdk-py and was initially inspired by notional, with the overall project structure adapted from hatch. Documentation is created using Material for MkDocs and hosted on GitHub Pages.
2 maintainers
Release files for ultimate-notion 0.10.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ultimate_notion-0.10.1.tar.gz | 133.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ultimate_notion-0.10.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 284.9 kB
Release files / ultimate_notion-0.10.1.tar.gz
| Download URL | ultimate_notion-0.10.1.tar.gz |
|---|---|
| Size | 133.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
80e1a4bceca76cf287f48514c79352e1f672701fc77b4a830acf48eb05d616bc
|
|
BLAKE2b-256 checksum How to use checksums |
b81d216f40465beccf227bab481dc48c92619aacad0fb648301ffb662e732eb1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 28, 2026.
Transparency logRelease files / ultimate_notion-0.10.1-py3-none-any.whl
| Download URL | ultimate_notion-0.10.1-py3-none-any.whl |
|---|---|
| Size | 151.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9a5d4ed323f03ba53e20978754481f5d3527d0b09b372688910a1c2351ed8a94
|
|
BLAKE2b-256 checksum How to use checksums |
0cc3be2da018eb6945032a5bb01ce192bf212dd7327f2ed1464ef6556543dc2f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 28, 2026.
Transparency log
