https://github.com/cachebag/nmrs
Rust bindings for NetworkManager over D-Bus.
https://github.com/cachebag/nmrs
dbus linux networkmanager rust wayland-compositor
Last synced: 5 days ago
JSON representation
Rust bindings for NetworkManager over D-Bus.
- Host: GitHub
- URL: https://github.com/cachebag/nmrs
- Owner: cachebag
- License: apache-2.0
- Created: 2025-09-24T19:38:57.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2026-04-24T20:28:15.000Z (6 days ago)
- Last Synced: 2026-04-24T21:09:24.950Z (6 days ago)
- Topics: dbus, linux, networkmanager, rust, wayland-compositor
- Language: Rust
- Homepage: https://cachebag.github.io/nmrs/
- Size: 1.05 MB
- Stars: 224
- Watchers: 2
- Forks: 21
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE-APACHE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
#
nmrs 🦀
[](https://crates.io/crates/nmrs)
[](https://discord.gg/Sk3VfrHrN4)
[](https://docs.rs/nmrs)
[](https://cachebag.github.io/nmrs/)
[](https://github.com/cachebag/nmrs/actions/workflows/ci.yml)
[](LICENSE)
An async-first Rust API for [NetworkManager](https://networkmanager.dev/) over [D-Bus](https://dbus.freedesktop.org/doc/dbus-specification.html). The goal is to provide a safe and simple high-level API for managing Wi-Fi connections on Linux systems, built on [`zbus`](https://docs.rs/zbus) for reliable D-Bus communication.
The project is divided into the following crates:
* `nmrs`: The core library providing NetworkManager bindings and Wi-Fi management API.
* `nmrs-gui`: A Wayland-compatible GTK4 graphical interface for NetworkManager.
[Jump to the GUI section of this repo](#installation)
## Documentation
- **[User Guide](https://cachebag.github.io/nmrs/)** - Comprehensive guide with tutorials and examples
- **[API Documentation](https://docs.rs/nmrs)** - Complete API reference on docs.rs
- **[Discord](https://discord.gg/Sk3VfrHrN4)** - Join our community for help and discussion
## Getting Started
_Please consider joining the [**Discord**](https://discord.gg/Sk3VfrHrN4). It's a welcoming community to both developers who want to contribute and/or learn about and discuss nmrs as well as users that would like to be engaged with the development process._
The best way to get started with `nmrs` is the [User Guide](https://cachebag.github.io/nmrs/), which includes comprehensive tutorials and examples. For detailed API information, see the [API documentation](https://docs.rs/nmrs).
## Sample usage
We'll create a simple example that scans for available networks and connects to one. Note that these examples require NetworkManager to be running on your Linux system with D-Bus access, obviously.
### Listing Networks
Scan for and display available Wi-Fi networks:
```rust,no_run
use nmrs::NetworkManager;
#[tokio::main]
async fn main() -> nmrs::Result<()> {
let nm = NetworkManager::new().await?;
// Scan for networks
let networks = nm.list_networks(None).await?;
for net in networks {
println!(
"{} - Signal: {}%, Security: {:?}",
net.ssid,
net.strength.unwrap_or(0),
net.security
);
}
Ok(())
}
```
### Now let's connect to a network...
Connect to a WPA-PSK protected network:
```rust,no_run
use nmrs::{NetworkManager, WifiSecurity};
#[tokio::main]
async fn main() -> nmrs::Result<()> {
let nm = NetworkManager::new().await?;
// Connect to a network
nm.connect("MyNetwork", None, WifiSecurity::WpaPsk {
psk: "password123".into()
}).await?;
// Check current connection
if let Some(ssid) = nm.current_ssid().await {
println!("Connected to: {}", ssid);
}
Ok(())
}
```
### Error Handling
All operations return `Result` with specific error variants:
```rust,no_run
use nmrs::{NetworkManager, WifiSecurity, ConnectionError};
#[tokio::main]
async fn main() -> nmrs::Result<()> {
let nm = NetworkManager::new().await?;
match nm.connect("MyNetwork", None, WifiSecurity::WpaPsk {
psk: "wrong_password".into()
}).await {
Ok(_) => println!("Connected successfully"),
Err(ConnectionError::AuthFailed) => eprintln!("Authentication failed - wrong password"),
Err(ConnectionError::NotFound) => eprintln!("Network not found or out of range"),
Err(ConnectionError::Timeout) => eprintln!("Connection timed out"),
Err(e) => eprintln!("Error: {}", e),
}
Ok(())
}
```
To follow and/or discuss the development of nmrs, you can join the [public Discord channel](https://discord.gg/Sk3VfrHrN4).
#
nmrs-gui
[](https://crates.io/crates/nmrs-gui)
[](https://github.com/cachebag/nmrs/actions/workflows/nix.yml)
This repository also includes `nmrs-gui`, a Wayland-compatible NetworkManager frontend built with GTK4.
### Installation
**Arch Linux (AUR)**
```bash
yay -S nmrs
# or
paru -S nmrs
```
**Nix**
```bash
nix-shell -p nmrs
```
### Configuration
**Waybar Integration**
```json
"network": {
"on-click": "nmrs"
}
```
**Tiling Window Managers** (Hyprland, Sway, i3)
```
windowrule = float 1, match:class org.nmrs.ui
```
**Custom Styling**
Edit `~/.config/nmrs/style.css` to customize the interface. There are also pre-defined themes you can pick from in the interface itself.
Roadmap / Implementation Status
### Devices
- [x] Generic
- [x] Wireless
- [ ] Any
- [X] Wired
- [ ] ADSL
- [X] Bluetooth
- [ ] Bond
- [ ] Bridge
- [ ] Dummy
- [ ] HSR *(NetworkManager ≥ 1.46)*
- [ ] Infiniband
- [ ] IP Tunnel
- [ ] IPVLAN *(NetworkManager ≥ 1.52)*
- [ ] Lowpan
- [ ] Loopback
- [ ] MACsec
- [ ] MACVLAN
- [ ] Modem
- [ ] OLPC Mesh
- [ ] OVS Bridge
- [ ] OVS Interface
- [ ] OVS Port
- [ ] PPP
- [ ] Statistics
- [ ] Team
- [ ] TUN/TAP
- [ ] VETH
- [ ] VLAN
- [ ] VRF
- [ ] VXLAN
- [ ] Wi-Fi P2P
- [ ] WiMAX
- [X] WireGuard
- [ ] WPAN
### Configurations
- [x] IPv4
- [x] IPv6
- [x] DHCPv4
- [x] DHCPv6
### Core Interfaces
- [x] NetworkManager *(partial)*
- [x] Device
- [x] Access Point
- [x] Active Connection
- [x] Settings
- [x] Settings Connection
- [x] Agent Manager
- [ ] Checkpoint
- [ ] DNS Manager
- [ ] PPP
- [x] Secret Agent
- [x] VPN Connection (WireGuard + plugin VPNs)
- [ ] VPN Plugin
- [ ] Wi-Fi P2P
- [ ] WiMAX NSP
## Contributing
Contributions are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
## Requirements
- **Rust**: 1.90.0+ for `nmrs`, 1.94.0+ for `nmrs-gui`
- **NetworkManager**: Running and accessible via D-Bus
- **Linux**: This library is Linux-specific
## License
This project is dual-licensed under either of the following licenses, at your option:
- MIT License
- Apache License, Version 2.0
You may use, copy, modify, and distribute this software under the terms of either license.
See the following files for full license texts:
- [MIT License](./LICENSE-MIT)
- [Apache License 2.0](./LICENSE-APACHE)
## Contributors
Thank you to everyone who has helped build, test, document, and review `nmrs`.
cachebag
stoutes
pluiee
JonnieCache
tristanmsct
Rifat-R
of-the-stars
okhsunrog
ruthwik-01
joncorv
AK78gz
pwsandoval
ritiek
shubhsingh5901
cinnamonstic
tuned-willow