Mactoast 🍞

An elegant and super easy to use Python library for creating customizable toast notifications on macOS.

Features

• 🎨 Customizable: Colors, size, position, timing, and more
• 💊 Modern Design: Borderless, modern UI with no title bar or buttons
• ⚡ Non-Blocking: Run toasts asynchronously without blocking your script
• 🎭 Animated: Smooth fade-in and fade-out animations
• 🪶 Lightweight: Minimal dependencies, uses a bundled native macOS app
• 🎯 Icons: Native SF Symbols support for beautiful icons
• 👆 Click to Dismiss: Tap any toast to dismiss it immediately
• 📏 Auto-Size: Automatically calculates optimal dimensions for your message
• 🔊 Sound Effects: Built-in notification sounds with custom sound support

Toast Styles

Success	Error	Warning	Info

Installation

pip install mactoast

Quick Start

from mactoast import toast

# Simple toast
toast("Hello from macOS!")

# With icon and sound
toast("Success!", icon="checkmark.circle.fill", sound="confirmation1")

# Preset styles
from mactoast import show_success, show_error, show_warning, show_info
show_success("File saved!")
show_error("Connection failed!")

Key Examples

Colors & Positioning

from mactoast import toast, ToastPosition

# Custom colors
toast("Blue toast", bg="#0080FF", text_color="#FFFFFF")

# Position
toast("Top Right", position=ToastPosition.TOP_RIGHT)
toast("Custom", position=(500, 500))

Auto-Size

# Automatically sizes to fit content
toast("Short!", auto_size=True)
toast("This is a longer message that wraps", auto_size=True)

Non-Blocking Mode

# Launch toast and continue immediately
process = toast("Background", blocking=False)
print(f"Toast PID: {process.pid}")

# Launch multiple toasts at once
for i in range(4):
    toast(f"Toast {i+1}", blocking=False)

Sound Effects

# 16 bundled sounds in 4 categories
toast("Beep!", sound="beep1")
toast("Success", sound="confirmation1")
toast("Pop!", sound="pop2")
toast("Sci-fi", sound="scifi1.m4a")

# Custom sound file
toast("Custom", sound="/path/to/sound.wav")

Icons (SF Symbols)

# Use any SF Symbol name
toast("Download complete", icon="arrow.down.circle.fill")
toast("Settings", icon="gearshape.fill")
toast("Message", icon="paperplane.fill")

Complete Documentation

For comprehensive documentation including:

• Full API reference
• ToastHUD Swift app architecture
• Sound system details
• Building from source
• Advanced examples
• Troubleshooting

See DOCS.md

Requirements

• macOS 10.15+
• Python 3.8+

Links

• Documentation: DOCS.md
• PyPI: https://pypi.org/project/mactoast/
• GitHub: https://github.com/rafa-rrayes/mactoast
• SF Symbols: https://developer.apple.com/sf-symbols/

License

MIT License - see LICENSE file for details