notify-rust

Linux/BSD

Primary target platform. Supports XDG specification (Gnome, KDE, XFCE, LXDC, Mate, etc.).

macOS

Supported via mac-notification-sys. Note that functionality is a subset of the Linux/BSD version due to NSNotification limitations.

Windows

Supported via winrt-notification.

To use notify-rust in your Rust project, add it to your Cargo.toml dependencies. It is recommended to use version 4.

[dependencies]
notify-rust = "4"

Urgency levels allow you to signal the importance of a notification. The mapping to platform-native behavior varies:

• Linux/BSD (XDG): Sent as a hint. Critical notifications are intended to not timeout automatically.
• Windows: Maps to toast scenarios. Low and Normal use the default scenario; Critical uses the Reminder scenario (stays on screen until dismissed).
• macOS: Maps to InterruptionLevel. Low $\rightarrow$ Passive, Normal $\rightarrow$ Active, Critical $\rightarrow$ TimeSensitive.

Note: For finer control on macOS (e.g., bypassing mute), use .interruption_level() directly if the preview-macos-un feature is enabled.

Use the Notification builder pattern to configure and display a desktop notification. You can set a summary (title), a body (message), and an icon. Calling .show() will trigger the platform-native notification system.

# use notify_rust::Notification;
# fn _doc() -> Result<(), Box<dyn std::error::Error>> {
Notification::new()
    .summary("☝️ A notification")
    .show()?;
# Ok(())
# }

Because notify-rust abstracts over different notification protocols (XDG/D-Bus, macOS NS/UN, Windows), some methods are only available on specific platforms. Use #[cfg] attributes to prevent compilation errors on unsupported platforms.

Example: Using macOS-only features

#[cfg(target_os = "macos")]
{
    // Use macOS specific methods or functions
}

Example: Using XDG/Linux features

#[cfg(all(unix, not(target_os = "macos")))]
{
    // Use XDG/D-Bus specific methods
}

You can create and show a basic notification using the Notification builder. This allows you to set a summary, body, and an icon.

use notify_rust::Notification;

Notification::new()
    .summary("Firefox News")
    .body("This will almost look like a real firefox notification.")
    .icon("firefox")
    .show()?;

To create a notification that stays on screen until acknowledged, use .timeout(0). You can also use Hint to provide metadata like categories or resident status (though resident status support varies by implementation).

use notify_rust::{Notification, Hint};

Notification::new()
    .summary("Category:email")
    .body("This has nothing to do with emails.\nIt should not go away until you acknowledge it.")
    .icon("thunderbird")
    .appname("thunderbird")
    .hint(Hint::Category("email".to_owned()))
    .hint(Hint::Resident(true)) // this is not supported by all implementations
    .timeout(0) // this however is
    .show()?;

The library is primarily designed for XDG-compliant Linux/BSD desktop environments (KDE, Gnome, XFCE, etc.).

Image Support

• images feature: Enables sending images via the image_data() or pixel-buffer API. This requires the image and lazy_static crates.
• image_path(): You can pass an image by file path using .image_path() on any platform without enabling the images feature. This maps to image-path on XDG, content_image on macOS, and is passed directly on Windows.

D-Bus Implementation

• d feature: Enables using dbus-rs instead of the default zbus.
• To actually use the dbus-rs implementation, you must either set the environment variable DBUSRS or compile with --no-default-features.

Use the Notification::new() builder pattern to create and display desktop notifications. You can customize the summary, body, icon, and timeout.

# use notify_rust::*;
Notification::new()
    .summary("Firefox News")
    .body("This will almost look like a real firefox notification.")
    .icon("firefox")
    .timeout(Timeout::Milliseconds(6000)) //milliseconds
    .show().unwrap();

On Unix systems (excluding macOS), you can add arbitrary metadata to a notification using the .hint() method. This is useful for passing custom data to notification servers or handlers.

# use notify_rust::{Notification, Hint};
# Notification::new()
#     .summary("Category:email")
#     .body("This should not go away until you acknowledge it.")
#     .icon("thunderbird")
#     .appname("thunderbird")
#     .hint(Hint::Category("email".to_owned()))
#     .hint(Hint::Resident(true))
#     .show();