Notion Python SDK

2.7.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install notion-client

Common errors

error ModuleNotFoundError: No module named 'notion_client' ↓

cause The 'notion-client' library has not been installed in the current Python environment.

fix

pip install notion-client

error notion_client.errors.APIResponseError: API response returned a 401 status code: Unauthorized ↓

cause The provided Notion API token is invalid, expired, or lacks the necessary permissions to access the requested resource.

fix

Verify 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.

error AttributeError: 'NotionResponse' object has no attribute 'results' ↓

cause NotionResponse objects behave like dictionaries, and their content should be accessed using dictionary-style key lookups (e.g., `['results']`) or the `.get()` method.

fix

Access the data using response['results'] or response.get('results') instead of response.results.

error notion_client.errors.APIResponseError: API response returned a 400 status code: body failed validation. Fix and try again. ↓

cause 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).

fix

Carefully 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.

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.

breaking The `NOTION_TOKEN` environment variable is required for client authentication but is not set, leading to a KeyError. ↓

fix Ensure the `NOTION_TOKEN` environment variable is properly set in the execution environment before running the application.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.24s 22.1M

3.10 slim (glibc) - - 0.18s 23M

3.11 alpine (musl) - - 0.38s 24.3M

3.11 slim (glibc) - - 0.31s 25M

3.12 alpine (musl) - - 0.55s 16.1M

3.12 slim (glibc) - - 0.52s 17M

3.13 alpine (musl) - - 0.58s 15.4M

3.13 slim (glibc) - - 0.51s 16M

3.9 alpine (musl) - - 0.22s 21.4M

3.9 slim (glibc) - - 0.19s 22M

Imports

Client
wrong
```
from notion_client import notion
```
correct
```
from notion_client import Client
```
Package is notion-client on PyPI but imports as notion_client. Common confusion.

AsyncClient

wrong

from notion_client import Client  # in async context

correct

from notion_client import AsyncClient

Use AsyncClient in asyncio environments, not the sync Client.

notion-py (abandoned)
wrong
```
from notion.client import NotionClient
```
correct
```
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 stale last tested: 2026-05-12

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