Crate win_desktop_utils 

Windows desktop helpers for Rust apps.

win-desktop-utils wraps a focused set of Windows desktop chores that many GUI, tray, installer-adjacent, and local utility apps need, while keeping raw Win32 shell, shortcut, mutex, known-folder, and elevation APIs out of the application code that uses them.

The low-level helpers stay available as small functions, and DesktopApp provides a friendlier facade for common app startup and app-data workflows. On non-Windows targets, the public API still compiles and operational helpers return Error::Unsupported.

When To Use This

Use this crate when a Windows desktop app needs to:

• open_with_default
• open_with_verb
• show_properties
• print_with_default
• open_url
• reveal_in_explorer
• open_containing_folder
• move_to_recycle_bin
• move_paths_to_recycle_bin
• empty_recycle_bin
• empty_recycle_bin_for_root
• create_shortcut
• create_url_shortcut
• single_instance
• single_instance_with_scope
• single_instance_with_options
• roaming_app_data
• local_app_data
• ensure_roaming_app_data
• ensure_local_app_data
• is_elevated
• restart_as_admin
• run_as_admin
• run_with_verb
• InstanceScope
• SingleInstanceOptions
• DesktopApp
• ShortcutOptions
• ShortcutIcon

This crate is Windows-first. Non-Windows builds provide stubs so cross-platform applications can depend on the crate without wrapping the dependency itself in cfg(windows).

Quick Start

fn main() -> Result<(), win_desktop_utils::Error> {
    let app = win_desktop_utils::DesktopApp::new(format!(
        "demo-app-{}",
        std::process::id()
    ))?;

    let _guard = match app.single_instance()? {
        Some(guard) => guard,
        None => {
            println!("already running");
            return Ok(());
        }
    };

    let local = app.ensure_local_data_dir()?;
    assert!(local.exists());

    Ok(())
}

Feature Flags

Default features enable the full API. Consumers can opt out and select only the modules they need:

[dependencies]
win-desktop-utils = { version = "0.5", default-features = false, features = ["paths", "instance"] }

Cross-platform applications can also keep the dependency Windows-only:

[target.'cfg(windows)'.dependencies]
win-desktop-utils = "0.5"

Available features:

• app: DesktopApp facade for app-data and single-instance startup.
• paths: per-user local and roaming app-data helpers.
• instance: named-mutex single-instance helpers.
• shell: shell opening, URL, Explorer, and shell-verb helpers.
• recycle-bin: Recycle Bin move and empty helpers.
• shortcuts: .lnk and .url shortcut helpers.
• elevation: elevation detection and shell-based relaunch helpers.

The default feature set is intentionally broad for convenience. Feature flags control this crate’s public modules; the underlying windows dependency uses one shared set of Win32 bindings when any Windows API feature is enabled.

Common Workflows

Startup guard plus app-data directory:

let app = win_desktop_utils::DesktopApp::new(format!(
    "workflow-demo-{}",
    std::process::id()
))?;
let _guard = app.single_instance()?.expect("first instance");
let config_dir = app.ensure_local_data_dir()?;
assert!(config_dir.exists());

Create a shortcut:

let shortcut = std::env::current_dir()?.join("notepad.lnk");
let options = win_desktop_utils::ShortcutOptions::new()
    .description("Open Notepad");
win_desktop_utils::create_shortcut(&shortcut, r"C:\Windows\notepad.exe", &options)?;

Relaunch the current executable as administrator:

use std::ffi::OsString;

if !win_desktop_utils::is_elevated()? {
    win_desktop_utils::restart_as_admin(&[OsString::from("--elevated")])?;
}

Behavior And Side Effects

• open_with_default requires a non-empty existing path.
• open_with_verb uses ShellExecuteW with the requested shell verb.
• show_properties and print_with_default are small shell-verb wrappers.
• open_url trims surrounding whitespace before delegating to the Windows shell.
• reveal_in_explorer requires an existing path and launches explorer.exe.
• open_containing_folder opens the existing path’s parent directory.
• move_to_recycle_bin requires an absolute existing path and uses IFileOperation on a dedicated STA thread for recycle-bin behavior.
• move_paths_to_recycle_bin validates all paths before starting one shell recycle-bin operation.
• empty_recycle_bin permanently empties the Recycle Bin without showing shell UI.
• create_shortcut uses IShellLinkW on a dedicated STA thread.
• roaming_app_data and local_app_data resolve their base directories via SHGetKnownFolderPath.
• single_instance uses a Local\... named mutex, so the lock is scoped to the current Windows session, and app_id cannot contain backslashes.
• single_instance_with_scope can opt into either the current-session or global mutex namespace.
• restart_as_admin starts a new elevated instance of the current executable, does not terminate the current process, and rejects arguments containing NUL bytes.
• run_as_admin and run_with_verb launch arbitrary commands through ShellExecuteW.

Stability

The minimum supported Rust version is 1.82. Public API compatibility is checked in CI with cargo-semver-checks, and dependency policy is checked with cargo-deny.

Re-exports

pub use error::Error;

pub use error::Result;

pub use app::DesktopApp;

pub use elevation::is_elevated;

pub use elevation::restart_as_admin;

pub use elevation::run_as_admin;

pub use elevation::run_with_verb;

pub use instance::single_instance;

pub use instance::single_instance_with_options;

pub use instance::single_instance_with_scope;

pub use instance::InstanceGuard;

pub use instance::InstanceScope;

pub use instance::SingleInstanceOptions;

pub use paths::ensure_local_app_data;

pub use paths::ensure_roaming_app_data;

pub use paths::local_app_data;

pub use paths::roaming_app_data;

pub use shell::empty_recycle_bin;

pub use shell::empty_recycle_bin_for_root;

pub use shell::move_paths_to_recycle_bin;

pub use shell::move_to_recycle_bin;

pub use shell::open_containing_folder;

pub use shell::open_url;

pub use shell::open_with_default;

pub use shell::open_with_verb;

pub use shell::print_with_default;

pub use shell::reveal_in_explorer;

pub use shell::show_properties;

pub use shortcuts::create_shortcut;

pub use shortcuts::create_url_shortcut;

pub use shortcuts::ShortcutIcon;

pub use shortcuts::ShortcutOptions;

Modules

app

Friendly facade for common desktop app startup workflows.

elevation

Elevation helpers for checking admin state and relaunching through UAC.

error

Shared error and result types for the crate.

instance

Single-instance helpers backed by named Windows mutexes.

paths

Helpers for resolving and creating per-user application data directories.

shell

Shell-facing helpers for opening files, URLs, Explorer selections, and the Recycle Bin.

shortcuts

Shortcut helpers for Windows .lnk and .url files.