Install & Compatibility
Where this runs
tested against v0.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.95 runs
installs and imports cleanly · install 0.0s · import 0.924s · 24.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.850s · 25MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NotionClient
✓ from notion.client import NotionClient
This is the primary client class for interacting with Notion.
Initializes the NotionClient using a `token_v2` (obtained from browser cookies, not an official integration token) and retrieves a Notion page. This example demonstrates basic page access and highlights the authentication method.
import os
from notion.client import NotionClient
# IMPORTANT: This library uses the internal Notion API and requires a token_v2 from browser cookies.
# It is unofficial and prone to breakage. For official API access, use 'notion-sdk-py'.
# Replace 'NOTION_TOKEN_V2' with your actual token_v2 from Notion.so browser cookies.
# This token is session-specific and can expire.
token_v2 = os.environ.get('NOTION_TOKEN_V2', '')
if not token_v2:
print("Error: NOTION_TOKEN_V2 environment variable not set. Please provide your token_v2 cookie value.")
else:
try:
client = NotionClient(token_v2=token_v2)
# Replace with the URL or ID of a Notion page you have access to
page_url = "https://www.notion.so/myorg/Test-c0d20a71c0944985ae96e661ccc99821" # Example URL
# Ensure the client's token has access to the page
page = client.get_block(page_url)
print(f"Successfully accessed page: {page.title}")
# Example: Update the page title
# page.title = "New Title from Python!"
# print(f"Page title updated to: {page.title}")
# Example: List children blocks (if any)
# for child in page.children:
# print(f" - Child block: {child.title}")
except Exception as e:
print(f"An error occurred: {e}")
print("Common issues: invalid token_v2, page not shared with the token's user, or Notion's internal API changed.")
Debug
Known issues
breakingThis library relies on Notion's unofficial/internal API, which is subject to change without notice. The v0.1.0 release (March 2026) introduced breaking changes to adapt to Notion's latest internal API (v3) modifications, including migration from `getRecordValues` to `syncRecordValues`, updated `queryCollection` aggregation, `getBacklinksForBlock` to `getBacklinksForBlockInitial`, and `search` endpoint sort parameter format.fixUpgrade to version 0.1.0 or newer and review the release notes for necessary code adjustments, as endpoint names and data formats may have changed.
affects: All versions prior to 0.1.0
gotchaAuthentication uses `token_v2`, obtained from Notion.so browser cookies. This token is session-specific, highly fragile, and prone to expiration or invalidation without warning, leading to `HTTPError` or `Unauthorized` errors.fixRegularly verify your `token_v2` and re-obtain it from your browser cookies if authentication fails. For a more stable and official integration, consider using the `notion-sdk-py` library with an official Notion integration token.
affects: All versions
gotchaThere is significant confusion between this unofficial `notion` library (`jamalex/notion-py` on GitHub) and the official Python SDK, `notion-sdk-py`. The two libraries are not fully compatible and use different authentication methods and API patterns.fixBe explicit about which library you intend to use. If targeting the official Notion API, use `pip install notion-client` and import `from notion_client import Client`. If you specifically need the features or internal API access of `jamalex/notion-py`, proceed with caution, understanding its unofficial nature.
affects: All versions
gotchaWhen using `client.get_block()`, ensure the `token_v2` has explicit read/write permissions to the specific Notion page or database you are trying to access. Lack of permissions often results in `object_not_found` or `restricted_resource` errors, even with a valid token.fixIn Notion, share the target page/database with the 'integration' associated with your `token_v2`. Ensure the page is not in a private or restricted state.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'notion'
The 'notion' library has not been installed in your Python environment, or the Python interpreter cannot find the installed package.
fixInstall the library using pip: `pip install notion`
HTTPError: 401 Client Error: Unauthorized
The Notion API token provided is invalid, has insufficient permissions, or is incorrectly formatted. This can also happen if your integration has not been granted access to the specific Notion page or database you are trying to interact with.
fixEnsure you are using a valid Notion integration token (often starting with `secret_` or `ntn_`). Verify that the integration has been explicitly shared with the page or database in Notion, and double-check that the token is passed correctly when initializing the client.
AttributeError: 'NoneType' object has no attribute 'items'
An API call to Notion likely returned `None` (e.g., because a resource was not found, or an error occurred during the API request), and your code attempted to access an attribute or method (like `.items()`) on this `None` object without proper error handling.
fixAdd checks for `None` or empty responses after making Notion API calls. Ensure that the IDs used to fetch Notion objects are correct and accessible by your integration. Wrap API calls in `try-except` blocks to gracefully handle potential `HTTPError`s or unexpected `None` returns.
404 Client Error: Not Found
The specific Notion page, database, or block ID you are trying to access does not exist, or your integration does not have permission to view that particular resource.
fixDouble-check the Notion ID (page, database, or block) for accuracy. Confirm that your Notion integration has been explicitly granted access to the page or database you are trying to interact with by adding it under 'Connections' in Notion.
429 Client Error: Too Many Requests
You have exceeded Notion's API rate limits, which are typically around three requests per second for standard integrations.
fixImplement rate limiting and exponential backoff in your code. When a 429 error is received, pause requests and retry after waiting for the duration specified in the `Retry-After` header of the API response.
Upgrade
Version history
0.1.0latest on PyPI · released Feb 16, 2026
Audit
Dependencies
No dependency data recorded yet.