Notion Python SDK

2.7.0 · active · verified Tue Mar 17

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.

Warnings

breaking API 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.
Fix: Replace all uses of 'archived' with 'in_trash' in request bodies and response handling.
breaking API version 2026-03-11: Append block children endpoint no longer accepts flat 'after' string parameter. Now requires a 'position' object.
Fix: Replace after='block_id' with position={'type': 'after_block', 'after_block': {'id': 'block_id'}}
breaking API version 2026-03-11: 'transcription' block type renamed to 'meeting_notes'.
Fix: Find and replace all references to 'transcription' block type with 'meeting_notes'.
breaking API 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.
Fix: Fetch data_source_id from database.data_sources array and pass it when creating pages. Migrate database endpoints to /v1/data_sources.
breaking notion.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.
Fix: Use notion.search() with filter={'value': 'database', 'property': 'object'} instead.
gotcha API token prefix changed from secret_ to ntn_ in September 2024. Code doing regex validation or prefix checks on tokens will reject new ntn_ tokens.
Fix: Remove any hardcoded secret_ prefix validation. Both secret_ and ntn_ tokens are valid.
gotcha SDK 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.
Fix: Pin API version explicitly: Client(auth=token, notion_version='2026-03-11')
gotcha notion-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.
Fix: Use notion-client (pip install notion-client) — the official SDK.

Install

pip install notion-client Python (official community SDK)

Imports

Client
```
from notion_client import Client
```
Package is notion-client on PyPI but imports as notion_client. Common confusion.
AsyncClient
```
from notion_client import AsyncClient
```
Use AsyncClient in asyncio environments, not the sync Client.
notion-py (abandoned)
```
from notion_client import Client
```
notion-py (jamalex/notion-py) is an unofficial abandoned package using private Notion APIs. Do not use. Use notion-client instead.

Quickstart

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'])

view raw JSON →