{"id":34094507,"url":"https://github.com/ultimate-notion/ultimate-notion","last_synced_at":"2026-03-17T16:03:42.499Z","repository":{"id":144669356,"uuid":"555762368","full_name":"ultimate-notion/ultimate-notion","owner":"ultimate-notion","description":"🚀 The ultimate Python client for Notion!","archived":false,"fork":false,"pushed_at":"2026-03-16T18:37:56.000Z","size":36370,"stargazers_count":113,"open_issues_count":21,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-17T05:33:37.862Z","etag":null,"topics":["notion","notion-api","notion-client","python"],"latest_commit_sha":null,"homepage":"https://ultimate-notion.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ultimate-notion.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"FlorianWilhelm","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":"https://www.paypal.me/FlorianWilhelm"}},"created_at":"2022-10-22T09:10:08.000Z","updated_at":"2026-03-13T08:37:16.000Z","dependencies_parsed_at":"2023-12-22T19:22:00.215Z","dependency_job_id":"cca3dc06-c5dc-4489-9717-008356a77c6a","html_url":"https://github.com/ultimate-notion/ultimate-notion","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/ultimate-notion/ultimate-notion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ultimate-notion%2Fultimate-notion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ultimate-notion%2Fultimate-notion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ultimate-notion%2Fultimate-notion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ultimate-notion%2Fultimate-notion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ultimate-notion","download_url":"https://codeload.github.com/ultimate-notion/ultimate-notion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ultimate-notion%2Fultimate-notion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30626906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T14:16:03.965Z","status":"ssl_error","status_checked_at":"2026-03-17T14:16:03.380Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["notion","notion-api","notion-client","python"],"created_at":"2025-12-14T15:03:46.538Z","updated_at":"2026-03-17T16:03:42.493Z","avatar_url":"https://github.com/ultimate-notion.png","language":"Python","funding_links":["https://github.com/sponsors/FlorianWilhelm","https://www.paypal.me/FlorianWilhelm"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg\nsrc=\"https://raw.githubusercontent.com/ultimate-notion/ultimate-notion/master/docs/assets/images/logo_with_text.svg\"\nalt=\"Ultimate-Notion logo\" width=\"500\" role=\"img\"\u003e\n\u003c/div\u003e\n\u003cbr/\u003e\n\nUltimate Notion is the ultimate Python client for [Notion]!\n\n|         |                                    |\n|---------|------------------------------------|\n| CI/CD   | [![Tests][Tests-image]][Tests-link] [![Coverage][Coverage-image]][Coverage-link] [![Publish Package][Publish-image]][Publish-link] [![Build Docs][Docs-image]][Docs-link] [![EffVer Versioning][EffVer-image]][EffVer-link] |\n| Package | [![PyPI - Version][PyPI_ver-image]][PyPI_ver-link] [![PyPI - Downloads][PyPI_down-image]][PyPI_down-link] [![PyPI - Python Version][PyPI_py-image]][PyPI_py-link] [![GitHub Sponsors][sponsor-image]][sponsor-link] |\n| Details | [![Hatch project][hatch-image]][hatch-link] [![Linting - Ruff][ruff-image]][ruff-link] [![Pre-Commit][precommit-image]][precommit-link] [![test - pytest][pytest-image]][pytest-link] [![Types - Mypy][mypy-image]][mypy-link] [![License - MIT][MIT-image]][MIT-link] [![Docs - mkdocs][mkdocs-image]][mkdocs-link] |\n\n## ✨ Features\n\n- 🐍 **Pythonic API** — Clean, intuitive Python interfaces with robust type annotations.\n- 🗂️ **CRUD operations** — Create, read, update, and delete Notion pages, databases, and blocks.\n- 🔎 **Rich querying capabilities** — Support for filters, sorting, pagination, and searching.\n- 🪄 **Flexible exports** — Convert Notion pages to Markdown, HTML, and databases to pandas, Polars.\n- ⬆️ **File upload support** — Easily upload and manage files in Notion pages and databases.\n- 🧩 **Built atop notion-sdk-py** — Enhancing the functionality of the popular low-level client.\n- 💯 **100% feature parity** — Full compatibility with all notion-sdk-py capabilities and more.\n- 🖥️ **Command line interface** — Convenient CLI for quick operations and automation scripts.\n- 🔒 **Token-based authentication** — Secure access using Notion integration tokens.\n- 🚀 **One-step setup** — Getting up to speed with a [simple setup guide].\n- 📜 **MIT licensed** — Released under the permissive [MIT license](LICENSE.txt) for maximum flexibility.\n\n👉 Want to learn more? Explore the full [feature breakdown].\n\n## 📦 Installation\n\nInstall the most recent release using [PyPI] with:\n\n```console\npip install ultimate-notion\n```\n\nor to install all additional dependencies, use:\n\n```console\npip install 'ultimate-notion[all]'\n```\n\n### 🧪 Installing the Development Version\n\nTo install the latest (potentially unstable) version directly from the main branch on GitHub:\n\n```console\npip install git+https://github.com/ultimate-notion/ultimate-notion.git@main\n```\n\nor with all optional dependencies:\n\n```console\npip install 'ultimate-notion[all] @ git+https://github.com/ultimate-notion/ultimate-notion.git@main'\n```\n\n## 🚀 Usage\n\nMake sure you have set the environment variable `NOTION_TOKEN` to your Notion\nintegration token. Then it's as simple as:\n\n```python\nimport ultimate_notion as uno\n\nPAGE_TITLE = 'Getting Started'\n\nwith uno.Session() as notion:\n    page = notion.search_page(PAGE_TITLE).item()\n    page.show()\n\n# Alternatively, without a context manager:\nnotion = uno.Session()\npage = notion.search_page(PAGE_TITLE).item()\npage.show()\nnotion.close()\n```\n\nCheck out the official [Ultimate Notion documentation] for more details.\nEspecially the page about [creating a Notion integration] to get the token.\n\n## 💬 Getting help\n\nIf you are stuck with a problem and need help or just want to brag about what you did,\nthe [Discussion] area is the right place for you. Here, you can ask questions, provide\nsuggesions and discuss with other users.\n\n## 🤝 Contributing\n\nAfter having cloned this repository:\n\n1. make sure [hatch] is installed globally, e.g. `pipx install hatch`,\n2. make sure [pre-commit] is installed globally, e.g. with `pipx install pre-commit`,\n\nand then you are already set up to start hacking. Use `hatch run test` to run the unit tests or `hatch run vcr-only`\nto run the offline unit tests using [VCR.py]. Regenerate the cassettes with `hatch run vcr-rewrite`.\nCheck out the environment setup of hatch in [pyproject.toml](pyproject.toml) for many more commands.\n\nIf you are using [VS Code], it's quite convenient to create a file  `.vscode/.env` with\n\n```ini\nNOTION_TOKEN=TOKEN_TO_YOUR_TEST_NOTION_ACCOUNT\nULTIMATE_NOTION_CONFIG=/path/to/repo/.ultimate-notion/config.toml\n```\n\nCheck out this [page about contributing] for more details.\n\n## 📄 License \u0026 Credits\n\nUltimate Notion is released under the terms of the [MIT license](LICENSE.txt).\nIt is built on top of [notion-sdk-py] and was initially inspired by [notional],\nwith the overall project structure adapted from [hatch].\nDocumentation is created using [Material for MkDocs] and hosted on [GitHub Pages].\n\n[Notion]: https://www.notion.so/\n[hatch]: https://hatch.pypa.io/\n[pre-commit]: https://pre-commit.com/\n[notional]: https://github.com/jheddings/notional/\n[notion-sdk-py]: https://github.com/ramnes/notion-sdk-py/\n[Material for MkDocs]: https://github.com/squidfunk/mkdocs-material\n[GitHub Pages]: https://docs.github.com/en/pages\n[Ultimate Notion documentation]: https://ultimate-notion.com/\n[creating a Notion integration]: https://ultimate-notion.com/latest/usage/getting_started/\n[page about contributing]: https://ultimate-notion.com/latest/contributing/\n[VS Code]: https://code.visualstudio.com/\n[PyPI]: https://pypi.org/\n[VCR.py]: https://vcrpy.readthedocs.io/\n[Discussion]: https://github.com/ultimate-notion/ultimate-notion/discussions\n\n[Tests-image]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/run-tests.yml/badge.svg\n[Tests-link]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/run-tests.yml\n[Coverage-image]: https://img.shields.io/coveralls/github/ultimate-notion/ultimate-notion/master.svg?logo=coveralls\u0026label=Coverage\n[Coverage-link]: https://coveralls.io/r/ultimate-notion/ultimate-notion\n[Publish-image]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/publish-pkg.yml/badge.svg\n[Publish-link]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/publish-pkg.yml\n[EffVer-image]: https://img.shields.io/badge/Versioning-EffVer-0097a7\n[EffVer-link]: https://jacobtomlinson.dev/effver\n[Docs-image]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/build-dev-docs.yml/badge.svg\n[Docs-link]: https://github.com/ultimate-notion/ultimate-notion/actions/workflows/build-dev-docs.yml\n[PyPI_ver-image]: https://img.shields.io/pypi/v/ultimate-notion.svg?logo=pypi\u0026label=PyPI\u0026logoColor=gold\n[PyPI_ver-link]: https://pypi.org/project/ultimate-notion/\n[PyPI_down-image]: https://img.shields.io/pypi/dm/ultimate-notion.svg?color=blue\u0026label=Downloads\u0026logo=pypi\u0026logoColor=gold\n[PyPI_down-link]: https://pypistats.org/packages/ultimate-notion\n[PyPI_py-image]: https://img.shields.io/pypi/pyversions/ultimate-notion.svg?logo=python\u0026label=Python\u0026logoColor=gold\n[PyPI_py-link]: https://pypi.org/project/ultimate-notion/\n[hatch-image]: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg\n[hatch-link]: https://github.com/pypa/hatch\n[ruff-image]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\n[ruff-link]: https://github.com/charliermarsh/ruff\n[mypy-image]: https://img.shields.io/badge/Types-mypy-blue.svg\n[mypy-link]: https://mypy-lang.org/\n[MIT-image]: https://img.shields.io/badge/License-MIT-9400d3.svg\n[MIT-link]: LICENSE.txt\n[sponsor-image]: https://img.shields.io/static/v1?label=Sponsor\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=ff69b4\n[sponsor-link]: https://github.com/sponsors/FlorianWilhelm\n[mkdocs-image]: https://img.shields.io/static/v1?label=‎\u0026message=mkdocs\u0026logo=Material+for+MkDocs\u0026color=526CFE\u0026logoColor=white\n[mkdocs-link]: https://ultimate-notion.com/\n[precommit-image]: https://img.shields.io/static/v1?label=‎\u0026message=pre-commit\u0026logo=pre-commit\u0026color=76877c\n[precommit-link]: https://pre-commit.com/\n[pytest-image]: https://img.shields.io/static/v1?label=‎\u0026message=Pytest\u0026logo=Pytest\u0026color=0A9EDC\u0026logoColor=white\n[pytest-link]:  https://docs.pytest.org/\n[simple setup guide]: https://ultimate-notion.com/latest/usage/getting_started/\n[feature breakdown]: https://ultimate-notion.com/latest/features/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fultimate-notion%2Fultimate-notion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fultimate-notion%2Fultimate-notion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fultimate-notion%2Fultimate-notion/lists"}