novu-py

library3.19.0pypypi✓ verified 24d ago

Open-source notification infrastructure. The official Python SDK is novu-py (pip install novu-py, import novu_py), NOT the older community packages novu or novu-python. Current version is 3.13.0 (Jan 2026). Three separate PyPI packages exist with different APIs — using the wrong one is the #1 footgun.

communication

pip install novu-py

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NOVU-PY

novu-py

communicationpythonv3.19.0

Install

3.3s avg

Import

1213ms

Disk

54MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.19.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

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 1.244s · 70.6MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 3.3s · import 1.182s · 40MB

54MB installed

● package 54MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Novu

✓ from novu_py import Novu

✗ from novu_py import Novu

Official novu-py SDK. Use context manager for resource cleanup in long-lived apps.

from novu_py import Novu # Initialize with your Novu API key novu = Novu(secret_key='YOUR_NOVU_API_KEY') # Trigger a notification workflow response = novu.trigger( workflow_id='welcome-email', # workflow ID from Novu dashboard to={ 'subscriber_id': 'user-123', 'email': 'alice@example.com', 'first_name': 'Alice' }, payload={ 'company': 'Acme Corp', 'action_url': 'https://app.example.com' } ) print(response) # Use as context manager for proper cleanup with Novu(secret_key='YOUR_NOVU_API_KEY') as novu: novu.trigger( workflow_id='password-reset', to={'subscriber_id': 'user-456'}, payload={'reset_url': 'https://app.example.com/reset/token'} )

Debug

Known issues

breakingThree separate PyPI packages exist: novu (community, dead), novu-python (community, dead), novu-py (official, active). pip install novu installs the wrong unmaintained package. LLMs almost always generate the wrong package name.

fix

pip install novu-py — import as from novu_py import Novu. Never use pip install novu or pip install novu-python for new projects.

affects: all

breakingThe old community novu package uses EventApi with name= (template name) and recipients= parameters. The official novu-py uses Novu.trigger() with workflow_id= and to= parameters. Code from tutorials using the old package will fail with ImportError or TypeError on the official SDK.

fix

Migrate from: EventApi(url, key).trigger(name=, recipients=) to: Novu(secret_key=).trigger(workflow_id=, to=)

affects: all

breakingnovu-py went through extremely rapid versioning: 0.x → 1.x → 3.x in under a year (Jan–Nov 2025). Each major version has breaking changes. Code from tutorials written for 0.x will not work on 3.x.

fix

Pin the version in requirements. Check the GitHub releases page before upgrading.

affects: all

gotchaThe Novu class should be used as a context manager in long-lived applications to properly close HTTPX connections. Forgetting to close the client leaks HTTP connections.

fix

Use with Novu(secret_key=...) as novu: pattern, or call novu.close() explicitly after use.

affects: all

gotchaNovu requires subscribers to exist before triggering notifications. Triggering to a non-existent subscriber_id auto-creates it, but without email/phone data the notification may silently fail to deliver.

fix

Create or upsert subscribers with full contact info before triggering: novu.subscribers.identify(subscriber_id='user-123', email='user@example.com').

affects: all

Upgrade

Version history

3.19.0latest on PyPI · released Aug 7, 2026

Audit

Dependencies

httpxrequiredRequired. Installed automatically.

pydanticrequiredRequired. Installed automatically.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/novuhq/novu-py.git ↗

packagehttps://pypi.org/project/novu-py/ ↗

homepagehttps://novu.co ↗