---
id: notion
version: "0.1.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# notion — Unofficial Python API client for Notion.so

License: permissive · Maintenance: active · Downloads: 997.2K/mo

## What it is and what it does

notion-py is an object-oriented wrapper around Notion.so's internal API v3 that lets you interact with Notion databases, pages, and blocks from Python code. It maps Notion's table structures (blocks, collections, spaces, users) to Python classes and properties, so you can read and modify Notion content programmatically—changing a page title in Python immediately updates the live Notion UI, and vice versa through a local cache and optional long-polling subscription.

The package handles automatic conversion between Notion's internal data formats and Python objects, supports traversing block hierarchies, adding/deleting blocks, and registering callbacks to respond to changes. It includes a central RecordStore that keeps all data in sync, so Record instances always reflect the latest state without storing state internally. Note that automatic Notion-to-Python updates are currently broken and disabled by default; you must call refresh() manually to pull changes from the server.

Use it for:

- Automate bulk updates to Notion databases—modify multiple rows or pages programmatically without manual UI interaction.
- Build a Python application that reads from Notion as a data source, treating Notion tables as a backend database.
- Create scripts that respond to Notion changes via callbacks, triggering external actions or updating other systems.
- Manage Notion page hierarchies and block organization—move, add, or delete blocks and nested content in bulk.
- Embed Notion content (collections, views, blocks) into Python workflows for reporting or data processing.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Unofficial Python client for Notion.so API v3 that maps Notion database tables to Python classes, enabling object-oriented read/write access to Notion pages, blocks, and collections.

Yes, if you need programmatic access to Notion and are comfortable with an unofficial API client. The package is actively maintained, has no known vulnerabilities, and low install friction. However, be aware that automatic Notion-to-Python updates are disabled and require manual refresh() calls, and the underlying Notion API v3 is undocumented and subject to change without notice.

## Install

pip install notion
uv add notion
poetry add notion

## Installing notion

Before you install: Low install friction with seven runtime dependencies (requests, commonmark, bs4, tzlocal, python-slugify, dictdiffer, cached-property). Actively maintained with recent commits and no known vulnerabilities. Requires Python 3.5 or greater.

License in practice: MIT license (permissive) allows commercial and private use with minimal restrictions, making it suitable for most projects without licensing concerns.

Quickstart:

pip install notion

from notion.client import NotionClient

client = NotionClient(token_v2="<your_token_v2>")
page = client.get_block("https://www.notion.so/myorg/Test-c0d20a71c0944985ae96e661ccc99821")
page.title = "Updated title"

Requires a valid Notion token_v2 obtained from browser cookies on a logged-in Notion.so session; Notion->Python automatic updating is currently disabled by default, requiring manual refresh() calls.

Verify before relying:

- Whether the long-polling background daemon thread for live updates is stable and production-ready despite the noted monitoring issues.
- Current state of the Notion API v3 compatibility—whether Notion has deprecated or changed the API since this client's last release.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 997.2K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

notion api python client, notion database python wrapper, notion page automation, notion block manipulation, notion collection access, notion sdk unofficial, python notion integration, notion-integration, api-wrapper, database-client

[View on SkillFed](https://skillfed.io/packages/notion) · [View on PyPI](https://pypi.org/project/notion/)