Skip to main content

pynotify-auto

Know when your Python scripts finish or fail.

Get alerts on your computer or on your phone when a run completes or crashes—so you can step away from your desk. Install once; nothing to import or add to your scripts.


🌐 VIEW LIVE DOCUMENTATION & SETUP GUIDE


Documentation PyPI version Supported OS Python Versions License: MIT

Why use this?

Traditional notification libraries require you to manually add decorators or extra lines of code to every script. pynotify-auto is different: it works automatically for every script in your environment.

  • Desktop + Mobile: Get native popups on your computer and real-time snapshots on your phone (Ntfy/Telegram).
  • Cross-Platform: Full support for Windows (Toast), macOS (Notification Center), and Linux (Libnotify).
  • Zero-Code Integration: Install once, and it works for all your scripts globally.
  • Smart Filtering: It stays quiet for quick tasks and only alerts you for the ones that actually take time.

Features

  • Zero-Code Integration: Works automatically across your entire system/environment.
  • Smart Thresholding: Only pings if the script ran for a meaningful amount of time (default > 5s).
  • Cross-Platform: Works on Windows, macOS, and Linux.
  • Configurable: Change the threshold or disable it via environment variables.

Compared to other tools

For a concise comparison with Apprise, Plyer, notifiers, and knockknock (integration style, desktop vs remote, when to use what), see docs/COMPARISON.md.

For a Medium / Dev.to–style article draft you can adapt and publish, see docs/article-notification-libraries-compared.md.

For a full tutorial vignette (install, hook, thresholds, modes, Ntfy/Telegram, env vars, CLI), see docs/tutorial-vignette.md.

Installation

Via Pip

pip install pynotify-auto

📱 Remote Notifications (Phone/Mobile)

pynotify-auto can track your script's progress and send real-time updates to your phone. It supports Ntfy.sh and Telegram.

Interactive Configuration

The easiest way to configure remote alerts is using the built-in wizard:

pynotify-auto --config

This interactive guide will help you choose your service and enter your credentials. It even remembers your settings so you can update them later by just pressing Enter.

Supported Backends

Service Setup Effort Benefits
Ntfy.sh ⭐ (Zero Signup) No account needed, lightweight, instant setup.
Telegram ⭐⭐ (Create Bot) Private, persistent history, premium formatting.

Setting up Ntfy.sh

  1. Install the Ntfy app on your phone.
  2. Subscribe to a unique topic name (e.g., my_script_alerts).
  3. Run pynotify-auto --config, choose ntfy, and enter that topic name.

Setting up Telegram

  1. Message @BotFather on Telegram to create a new bot and get your API Token.
  2. Message @userinfobot to get your Chat ID.
  3. Run pynotify-auto --config, choose telegram, and enter your Token and Chat ID.

⏳ Real-Time Progress Tracking

Once enabled, pynotify-auto will automatically:

  • Ping your phone every 30 minutes (configurable) with a snapshot of your logs.
  • Notify you immediately if the script crashes with the error traceback.
  • Notify you when the script finishes successfully.

⚙️ Advanced Configuration

All settings are stored in ~/.pynotify.json. You can also override them using environment variables:

Setting JSON Key Env Variable Default
Threshold threshold PYNOTIFY_THRESHOLD 5.0 (sec)
Progress Interval progress_interval_minutes PYNOTIFY_PROGRESS_INTERVAL 30 (min)
Log History log_lines PYNOTIFY_LOG_LINES 10
Backend remote_backend PYNOTIFY_REMOTE_BACKEND None
Ntfy Topic ntfy_topic PYNOTIFY_NTFY_TOPIC None
Telegram Token telegram_bot_token PYNOTIFY_TELEGRAM_TOKEN None
Telegram Chat ID telegram_chat_id PYNOTIFY_TELEGRAM_CHAT_ID None

The "Zero-Code" progress tracker automatically intercepts your script's output (stdout and stderr). It captures print() statements, standard logging, and even crash tracebacks without requiring any changes to your code.

🤝 Used By

Are you using pynotify-auto in your project? We'd love to feature you here! Open a PR to add your project to the list.

License

MIT

Contributing

I'm open to contributions! Feel free to fork the repo and open a PR if you have bug fixes or new notification backends (Slack, Discord, etc.) you'd like to add.

Check the comprehensive test suite for examples on how to run tests locally.

Metadata

Release files for pynotify-auto 0.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pynotify-auto 0.6.2
File Size Uploaded Provenance Actions
pynotify_auto-0.6.2.tar.gz 19.8 kB Without provenance Details for pynotify_auto-0.6.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pynotify-auto 0.6.2
File Interpreter ABI Platform Actions
pynotify_auto-0.6.2-py3-none-any.whl Python 3 none any Details for pynotify_auto-0.6.2-py3-none-any.whl

Total release size: 35.5 kB

Release files / pynotify_auto-0.6.2.tar.gz

Download URL pynotify_auto-0.6.2.tar.gz
Size 19.8 kB
Tags Source
SHA-256 checksum
How to use checksums
3a82248153c04b1ac64f03e84c0ccd0c7de836ab394e6fb641b169e024b03ef7
BLAKE2b-256 checksum
How to use checksums
ba9748b655a86c888a40776907840190dfe1c9493079841fb2a91ddcc5f82790
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.12

Release files / pynotify_auto-0.6.2-py3-none-any.whl

Download URL pynotify_auto-0.6.2-py3-none-any.whl
Size 15.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
38b33c15f9f311d2ed9c3a303628aee7952346cceede078ee45cfabb31883b1e
BLAKE2b-256 checksum
How to use checksums
2e336a773a649b07db8c5551e5740bf88ac0594a03c4807b95c01b642c2a3992
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.12

Security for pynotify-auto 0.6.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page