NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #2086 most downloaded on PyPI
Python client for the official Notion API
Latest stable
3.1.0
Last release 6 months ago
12 May 2026
Release timing varies
gaps range from 2 months to 12 months
Most releases are documented
notes for 19 of 22 stable releases
1 version withdrawn
withdrawn after publishing
6 years old
23 releases · first in 2021
Drag across the ruler to compare, or tap a release to open it.
This version adds support for a whole bunch of new endpoints!
This version adds support for a whole bunch of new endpoints!
It also brings automatic retries on rate limits and transient server errors (configurable at the ClientOptions level).
A few new helpers and constants have been added as well: is_full_view, is_http_response_error, DEFAULT_TIMEOUT_MS and MIN_VIEW_COLUMN_WIDTH.
Thanks to @tsinglinrain for the help.
client.py following notion-sdk-js by @tsinglinrain in https://github.com/ramnes/notion-sdk-py/pull/314pages.retrieve_markdown() and pages.update_markdown() endpoints by @ramnes in https://github.com/ramnes/notion-sdk-py/pull/317gateway_timeout to APIErrorCode enum by @ramnes in https://github.com/ramnes/notion-sdk-py/pull/322custom_emojis.list() endpoint by @ramnes in https://github.com/ramnes/notion-sdk-py/pull/323Full Changelog: https://github.com/ramnes/notion-sdk-py/compare/3.0.0...3.1.0
Your coding agent can read these notes before it upgrades. Set up the MCP server →
⚠️ Beware of the following breaking changes:
Thanks to all the contributors for this new major version!
⚠️ Beware of the following breaking changes:
is_full_page_or_database has been removed. Use is_full_page_or_data_source instead.is_api_error_code has been made private.intro-to-notion-api example for Python SDK by @Sumeet213 in https://github.com/ramnes/notion-sdk-py/pull/297data sources in helpers.py and more namespace exports by @tsinglinrain in https://github.com/ramnes/notion-sdk-py/pull/299errors.py following JS SDK implementation by @tsinglinrain in https://github.com/ramnes/notion-sdk-py/pull/308error.py following notion-sdk-js by @tsinglinrain in https://github.com/ramnes/notion-sdk-py/pull/312Full Changelog: https://github.com/ramnes/notion-sdk-py/compare/2.7.0...3.0.0
Add generate random data example by @Sumeet213 in https://github.com/ramnes/notion-sdk-py/pull/292
additional_data and request_id fields in the APIResponseError class by @tsinglinrain in https://github.com/ramnes/notion-sdk-py/pull/293additional_data and request_id tests by @tsinglinrain in https://github.com/ramnes/notion-sdk-py/pull/295Full Changelog: https://github.com/ramnes/notion-sdk-py/compare/2.6.0...2.7.0
⚠️ Beware, Notion-Version has been upgraded to 2025-09-03. This version of the SDK is not compatible with older versions of the API. See Notion's upgr
⚠️ Beware, Notion-Version has been upgraded to 2025-09-03. This version of the SDK is not compatible with older versions of the API. See Notion's upgrade guide to learn more.
attachements and display_name to body by @zubu007 in https://github.com/ramnes/notion-sdk-py/pull/281Full Changelog: https://github.com/ramnes/notion-sdk-py/compare/2.5.0...2.6.0
Support file uploads by @tsinglinrain in https://github.com/ramnes/notion-sdk-py/pull/270
Full Changelog: https://github.com/ramnes/notion-sdk-py/compare/2.4.0...2.5.0
Add column body param for block updates
column body param for block updatesFull Changelog: https://github.com/ramnes/notion-sdk-py/compare/2.3.0...2.4.0
Official support of Python 3.13
in_trash property to PagesEndpoint, by @jjongguet in https://github.com/ramnes/notion-sdk-py/pull/236text should be rich_text, by @yangxinyi-bigdata in https://github.com/ramnes/notion-sdk-py/pull/232Full Changelog: https://github.com/ramnes/notion-sdk-py/compare/2.2.1...2.3.0
Quick fix for iteration helpers that got broken in 2.2.0.
Quick fix for iteration helpers that got broken in 2.2.0.
Icons and covers can now be removed from pages. (Thanks to @FlorianWilhelm for the nudge!)
Full Changelog: https://github.com/ramnes/notion-sdk-py/compare/2.1.0...2.2.0
100% Coverage 🥳 by @mutt0-ds in https://github.com/ramnes/notion-sdk-py/pull/168
Thanks to all of you!
Full Changelog: https://github.com/ramnes/notion-sdk-py/compare/2.0.0...2.1.0
⚠️ Beware, Notion-Version has been upgraded to 2022-06-28 and it brings breaking changes.
This major version update mostly adds new helpers, support for the comments API, more tests, and Python 3.11.
⚠️ Beware, Notion-Version has been upgraded to 2022-06-28 and it brings breaking changes.
Thanks to our new contributors, @ssredpanda and @andrewdircks, as well as to @mutt0-ds for his important work on this release!
Full Changelog: https://github.com/ramnes/notion-sdk-py/compare/1.0.0...2.0.0
Nothing published for this version
⚠️ Beware, Notion-Version has been upgraded to 2022-02-22 and it brings breaking changes.
Let's get out of beta and release 1.0.0!
⚠️ Beware, Notion-Version has been upgraded to 2022-02-22 and it brings breaking changes.
Thanks to our new contributor for this release, @sudosubin!
Full Changelog: https://github.com/ramnes/notion-sdk-py/compare/0.9.0...1.0.0
Adds support for the recent Notion API changes and timeout errors. It also doesn't send null values anymore (see issue #94).
Adds support for the recent Notion API changes and timeout errors. It also doesn't send null values anymore (see issue #94).
Thanks to this release contributors, @mutt0-ds and @nicobako!
Adds support for the recent Notion API changes.
Adds support for the recent Notion API changes.
Nothing published for this version
Beware, Notion-Version has been upgraded to 2021-08-16 and it brings breaking changes.
Adds support for the recent Notion API changes.
Beware, Notion-Version has been upgraded to 2021-08-16 and it brings breaking changes.
Adds support for the recent Notion API changes. Upgrading should be seamless from 0.4.0 onwards.
Adds support for the recent Notion API changes. Upgrading should be seamless from 0.4.0 onwards.
Mostly adds support for the recent Notion API changes, and per-function authentication. Upgrading from 0.4.0 should be seamless.
Mostly adds support for the recent Notion API changes, and per-function authentication. Upgrading from 0.4.0 should be seamless.
Thanks to contributors of this release: @aahnik, @nlecoy, @mixeden and @Thompsonmina!
> :warning: Breaking change — The client methods now return the response content directly, so you don't need to call .json() on results anymore.
We now have error handling and complete type hinting, thanks to @Blue-Hope and @aahnik. Kudos to you two!
:warning: Breaking change — The client methods now return the response content directly, so you don't need to call
.json()on results anymore.
All endpoints are now implemented! It still needs polishing but it's mostly functional.
All endpoints are now implemented! It still needs polishing but it's mostly functional.
Nothing published for this version
Nothing published for this version
One column per quarter.