webbrowser Rust Library

The webbrowser crate provides several behavioral guarantees across platforms:

• Browser guarantee: Unlike other libraries that might trigger a system editor for local HTML files, webbrowser guarantees that a browser is opened even for local file:/// paths.
• Execution Model: The library is Non-Blocking for GUI-based browsers (e.g., Chrome, Firefox) but Blocking for text-based browsers (e.g., lynx).
• Output Management: Output (stdout/stderr) from GUI-based browsers is suppressed by default to prevent polluting your application's output. If you need to see this output, use webbrowser::open_browser_with_options.

Supported Platforms

Consistent Behavior Guarantees

• Browser guarantee: Unlike other libraries, webbrowser guarantees that a browser is opened even for local files (preventing local HTML files from accidentally opening in a text editor).
• Non-Blocking/Blocking: GUI-based browsers (Chrome, Firefox, etc.) are non-blocking, while text-based browsers (lynx, etc.) are blocking.
• Suppressed output: By default, stdout/stderr from GUI browsers are suppressed to prevent polluting the main program's output.

You can enable specific features in your Cargo.toml to modify the library's behavior:

• hardened: Disables handling of non-http(s) URLs (like file:///) as a security precaution.
• disable-wsl: Disables the WSL file implementation (though http still works).
• wasm-console: Enables logging to the WASM console (only applicable on the wasm platform).

Use webbrowser::open to open a URL or a local file in the platform's default web browser. This function returns a Result<(), Error> which can be used to verify if the operation succeeded.

use webbrowser;

if webbrowser::open("http://github.com").is_ok() {
    // ...
}

The webbrowser crate can be configured with the following features at compile time:

• hardened: Disables handling of non-http(s) URLs (e.g., file:///) as a security precaution. If enabled, open and open_browser will return an error for local files.
• disable-wsl: Disables the WSL file implementation (HTTP still works).
• wasm-console: Enables logging to the WebAssembly console (only applicable on the wasm platform).

The library supports a wide range of platforms. On Linux/WSL and Unix-like systems, it respects the $BROWSER environment variable, allowing you to use browsers other than the system default.

The BrowserOptions struct allows you to customize the browser invocation. Use BrowserOptions::new() to start with default values (which include suppressing stdout/stderr by default).

Available configuration methods:

• with_suppress_output(bool): Determines whether stdout/stderr of the browser command is suppressed.
• with_target_hint(&str): Provides a hint to the browser for the target (e.g., _blank). Note: This is a hint and is only guaranteed to be honored on wasm platforms.
• with_dry_run(bool): If true, does not execute the command but returns whether it would likely have succeeded.
• with_dont_switch(bool): (macOS only) Prevents the browser window from switching to the foreground.

let mut options = BrowserOptions::new();
options.with_suppress_output(false).with_dry_run(true);

Use webbrowser::open to open a URL using the system's default web browser. This is the simplest way to trigger a browser opening.

Returns Ok(()) if the invocation was successful, or an Err if the browser was not found, there was an error opening it, or if the hardened feature is enabled and the URL is not http or https.

use webbrowser;

if webbrowser::open("http://github.com").is_ok() {
    // ...
}

Use webbrowser::open_browser to specify a particular browser from the Browser enum. This is useful when you want to target a specific application like Chrome or Firefox instead of the system default.

Returns Ok(()) if successful, or an Err if the requested browser is unavailable or an error occurs during invocation.

use webbrowser::{open_browser, Browser};

if open_browser(Browser::Firefox, "http://github.com").is_ok() {
    // ...
}

Use webbrowser::open_browser_with_options to provide fine-grained control over how the browser is launched. This allows you to override default behaviors like output suppression or target hints.

Example of configuring options using the builder pattern:

use webbrowser::{open_browser_with_options, Browser, BrowserOptions};

let options = BrowserOptions::new()
    .with_suppress_output(false)
    .with_target_hint("_blank");

if open_browser_with_options(Browser::Default, "http://github.com", &options).is_ok() {
    // ...
}

The Browser enum defines the supported browser types. You can use these to target specific browsers via open_browser or open_browser_with_options.

Supported variants:

• Browser::Default: The operating system's default browser.
• Browser::Firefox
• Browser::InternetExplorer
• Browser::Chrome
• Browser::Opera
• Browser::Safari
• Browser::WebPositive

Useful methods:

• Browser::is_available(): Returns true if a default browser is detected in the system.
• browser.exists(): Returns true if the specific browser variant is detected in the system.

use webbrowser::Browser;

// Check if default browser exists
if Browser::is_available() {
    // ...
}

// Check if Chrome specifically exists
if Browser::Chrome.exists() {
    // ...
}