Official Python client for the Notion API, maintained by the community (ramnes/notion-sdk-py). Current version is 2.7.0 (Oct 2025). Notion API itself is versioned separately — the SDK version and the API version are two different things. Multiple breaking API versions have shipped in 2024-2026.
Install & Compatibility
Where this runs
tested against v3.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.374s · 22.1MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 2.2s · import 0.330s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from notion_client import Client
✗ from notion_client import notion
Package is notion-client on PyPI but imports as notion_client. Common confusion.
AsyncClient
✓ from notion_client import AsyncClient
✗ from notion_client import Client # in async context
Use AsyncClient in asyncio environments, not the sync Client.
notion-py (abandoned)
✓ from notion_client import Client
✗ from notion.client import NotionClient
notion-py (jamalex/notion-py) is an unofficial abandoned package using private Notion APIs. Do not use. Use notion-client instead.
Minimal Notion read using notion-client 2.7.x.
import os
from notion_client import Client
notion = Client(auth=os.environ['NOTION_TOKEN'])
# query a database
results = notion.databases.query(
database_id='YOUR_DATABASE_ID'
)
# retrieve a page
page = notion.pages.retrieve(page_id='YOUR_PAGE_ID')
print(page['properties'])
Debug
Known issues
breakingAPI version 2026-03-11 (released Mar 11 2026) removes 'archived' field — replaced by 'in_trash'. Any code reading or writing 'archived' on pages, databases, or blocks will break when using this API version.fixReplace all uses of 'archived' with 'in_trash' in request bodies and response handling.
affects: API version >= 2026-03-11
breakingAPI version 2026-03-11: Append block children endpoint no longer accepts flat 'after' string parameter. Now requires a 'position' object.fixReplace after='block_id' with position={'type': 'after_block', 'after_block': {'id': 'block_id'}} affects: API version >= 2026-03-11
breakingAPI version 2026-03-11: 'transcription' block type renamed to 'meeting_notes'.fixFind and replace all references to 'transcription' block type with 'meeting_notes'.
affects: API version >= 2026-03-11
breakingAPI version 2025-09-03: Multi-source databases introduced. /v1/databases endpoints now refer to the database container, not the data source. Integrations that create pages or define relations must now pass data_source_id.fixFetch data_source_id from database.data_sources array and pass it when creating pages. Migrate database endpoints to /v1/data_sources.
affects: API version >= 2025-09-03
breakingnotion.databases.list() raises APIResponseError: 'This API is deprecated'. The List databases endpoint was removed in API version 2022-02-22. Still widely referenced in tutorials.fixUse notion.search() with filter={'value': 'database', 'property': 'object'} instead. affects: all current versions
gotchaAPI token prefix changed from secret_ to ntn_ in September 2024. Code doing regex validation or prefix checks on tokens will reject new ntn_ tokens.fixRemove any hardcoded secret_ prefix validation. Both secret_ and ntn_ tokens are valid.
affects: all
gotchaSDK version and Notion API version are independent. notion-client 2.7.0 does not automatically use the latest API version. Default API version may lag behind latest.fixPin API version explicitly: Client(auth=token, notion_version='2026-03-11')
affects: all
gotchanotion-py (PyPI: notion) is an unofficial package using private undocumented Notion APIs. It breaks without warning when Notion changes internals. Widely referenced in old tutorials.fixUse notion-client (pip install notion-client) — the official SDK.
affects: all
breakingThe `NOTION_TOKEN` environment variable is required for client authentication but is not set, leading to a KeyError.fixEnsure the `NOTION_TOKEN` environment variable is properly set in the execution environment before running the application.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'notion_client'
The 'notion-client' library has not been installed in the current Python environment.
fixpip install notion-client
notion_client.errors.APIResponseError: API response returned a 401 status code: Unauthorized
The provided Notion API token is invalid, expired, or lacks the necessary permissions to access the requested resource.
fixVerify your `NOTION_TOKEN` is correct and that your Notion integration has been granted access to the specific page or database you are trying to interact with.
AttributeError: 'NotionResponse' object has no attribute 'results'
NotionResponse objects behave like dictionaries, and their content should be accessed using dictionary-style key lookups (e.g., `['results']`) or the `.get()` method.
fixAccess the data using `response['results']` or `response.get('results')` instead of `response.results`. notion_client.errors.APIResponseError: API response returned a 400 status code: body failed validation. Fix and try again.
The request body sent to the Notion API contains invalid data, is missing required fields, or has an incorrect structure for properties (e.g., wrong type for a property value).
fixCarefully review the official Notion API documentation for the specific endpoint (e.g., creating a page or updating properties) and ensure your Python dictionary matches the expected JSON structure.
Audit
Dependencies
httpxrequiredHTTP client used internally by notion-client.