Notion-Py – An Unofficial Python API client for Notion

Notion is a web-based collaboration platform that allows users to work with kanban boards, tasks, wikis, and databases in the same interface. Notion brings together the best aspects of Trello, spreadsheets, relational databases, rich WYSIWYG Markdown editing, TODO lists, and more, into a single, seamless, flexible, and intuitive system.

There is a small problem with Notion : it doesn’t have any documented API for developers. However, Python enthusiast Jamie Alexandre has created notion-py, an unofficial Python wrapper for the internal Notion v3 API.

What is Notion-Py


Notion-Py is an unofficial Python wrapper for the internal Notion v3 API.

The Notion front-end is written in JavaScript that relies on a private API to do most of its operations. Notion-Py reverse-engineered that and wrap it into a nice Python API.

In Notion-Py, Notion objects such as nodes, blocks, embedded contents, etc are mapped to native Python classes/attributes and vice versa.

Notion-Py also allows real-time reactive two-way data binding (changing Python object -> live updating of Notion UI, and vice-versa) _(Note: Notion->Python automatic updating is currently broken and hence disabled by default; call MARKDOWN_HASH6321d722784ffae7e9d6708f85dfc3b0MARKDOWNHASH to update, in the meantime, while monitoring is being fixed)

Notion-Py Installation and Usage

Notion-Py requires Python version 3.5 or later to be installed on your system to be able to work properly. Once you’ve had Python preinstalled, you can get Notion-Py by running the following command on any terminal window.

pip install notion

Then, you have to obtain an access token so that Notion-Py can access your private notes and perform operations on them.

In order to find the access token, first you need to be logged in to Suppose you’re using Chrome-based browsers, on any Notion page, right-click and select Inspect or press F12 on your keyboard to open up the Chrome DevTools.

Chrome DevTools on Notion

Then, switch over to Application tab. In the left pane, select Cookies and find token_v2 value in the right area.

Notion token_v2

Save the token in Value column as you will use it later to authorize your API. Below is a simple example of how you can log in and change the title of a page using Notion-Py.

from notion.client import NotionClient

# Obtain the `token_v2` value by inspecting your browser cookies on a logged-in (non-guest) session on
client = NotionClient(token_v2="")

# Replace this URL with the URL of the page you want to edit
page = client.get_block("")

print("The old title is:", page.title)

# Update the title of the page
page.title = "The title has now changed, and has *live-updated* in the browser!"

The changes are updated instantly as API requests are made right after you run the code. You can also use NotionClient in an interactive shell and watch the page changes with your code.

Notion-Py in action

Notion-Py is an actively developing product and you should expect breaking changes in its API. More information and code examples can be found at its official Github repository. Another alternative to Notion-Py is notion-sdk-py written by Guillaume Gelin.

Leave a Comment