win11toast

Install the win11toast package using pip to enable Windows 10 and 11 toast notifications via WinRT.

pip install win11toast

Use the toast() function to display a simple notification. You can provide a title and an optional body text.

from win11toast import toast

toast('Hello Python🐍')

You can trigger a local Python script when a toast is clicked by passing the path to the script in on_click.

Note: Since the execution directory defaults to C:\Windows\system32, ensure your script handles paths correctly (e.g., using os.chdir()). For background execution without a visible console, consider using pythonw.exe.

from win11toast import toast

toast('Hello Pythonista', 'Click to run python script', on_click=r'C:\Users\Admin\Downloads\handler.pyw')

Use notify() to create an initial progress toast and update_progress() to update the status and value of an existing progress bar.

from time import sleep
from win11toast import notify, update_progress

# Initialize progress
notify(progress={
    'title': 'YouTube',
    'status': 'Downloading...',
    'value': '0',
    'valueStringOverride': '0/15 videos'
})

# Update progress in a loop
for i in range(1, 15+1):
    sleep(1)
    update_progress({'value': i/15, 'valueStringOverride': f'{i}/15 videos'})

# Final status update
update_progress({'status': 'Completed!'})

You can customize the visual appearance using icon and image parameters.

• Icon: Small icon displayed in the toast. Can be a URL or a dictionary specifying src and placement (e.g., 'appLogoOverride' for a square look).
• Image: Larger image. Can be a URL or a dictionary specifying src and placement (e.g., 'hero' for a large hero image).

from win11toast import toast

# Simple icon
toast('Hello', 'Hello from Python', icon='https://unsplash.it/64?image=669')

# Square icon via dictionary
icon = {
    'src': 'https://unsplash.it/64?image=669',
    'placement': 'appLogoOverride'
}
toast('Hello', 'Hello from Python', icon=icon)

# Hero image
image = {
    'src': 'https://4.bp.blogspot.com/-u-uyq3FEqeY/UkJLl773BHI/AAAAAAAAYPQ/7bY05EeF1oI/s800/cooking_toaster.png',
    'placement': 'hero'
}
toast('Hello', 'Hello from Python', image=image)

Customize the sound played with the toast using the audio parameter. You can provide:

• A system sound URI (e.g., ms-winsoundevent:Notification.Looping.Alarm).
• A URL to an audio file.
• A local file path.
• A dictionary to enable loop or set the toast to silent.

from win11toast import toast

# System sound
toast('Hello', 'Hello from Python', audio='ms-winsoundevent:Notification.Looping.Alarm')

# URL audio
toast('Hello', 'Hello from Python', audio='https://nyanpass.com/nyanpass.mp3')

# Local file audio
toast('Hello', 'Hello from Python', audio=r'C:\Users\Admin\Downloads\nyanpass.mp3')

# Looping audio
toast('Hello', 'Hello from Python', audio={'loop': 'true'})

# Silent toast
toast('Hello Python🐍', audio={'silent': 'true'})

You can add a body to the notification and define an on_click action. The on_click parameter can be a URL string or a callback function.

from win11toast import toast

# Open a URL on click
toast('Hello Python', 'Click to open url', on_click='https://www.python.org')

# Execute a callback function
toast('Hello Python', 'Click to open url', on_click=lambda args: print('clicked!', args))

Win11toast supports Optical Character Recognition (OCR) and Text-to-Speech (Speak).

• OCR: Pass a URL or a dictionary with lang and the local path to an image to extract text.
• Speak: Use the dialogue parameter to have the system read text aloud.

from win11toast import toast

# OCR from URL
toast(ocr='https://i.imgur.com/oYojrJW.png')

# OCR with language and local file
toast(ocr={'lang': 'ja', 'ocr': r'C:\Users\Admin\Downloads\hello.png'})

# Text-to-Speech
toast('Hello Python🐍', dialogue='Hello world')

Depending on your application flow, you can use different notification methods:

• notify(): A non-blocking version of toast() that doesn't wait for the toast to be processed.
• toast_async(): An asynchronous version for use in asyncio environments (like Jupyter notebooks).

from win11toast import notify, toast_async
import asyncio

# Non-blocking
notify('Hello Python', 'Non-blocking message')

# Async usage
async def main():
    await toast_async('Hello Python', 'Async message')

asyncio.run(main())

Control how long a toast stays visible or its priority using duration and scenario.

• duration: Set to 'long' to display for approximately 25 seconds.
• scenario: Defines the toast's purpose (e.g., 'incomingCall', 'alarm', 'reminder', or 'urgent'). Certain scenarios may prevent the toast from timing out.

from win11toast import toast

# Long duration
toast('Hello Python🐍', duration='long')

# Specific scenario (e.g., no timeout for calls)
toast('Hello Python🐍', scenario='incomingCall')