# bluetui: a ratatui front end for BlueZ on Linux

> bluetui is a Rust terminal UI that drives BlueZ over D-Bus through the bluer crate. It is for Linux users who want adapter and device control without leaving the terminal, and it assumes BlueZ is already running on the machine.

**pythops/bluetui** — 🛜 TUI for managing bluetooth on Linux

- Repository: https://github.com/pythops/bluetui
- Stars: 3,017 · Forks: 79
- Language: Rust
- License: GPL-3.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/pythops-bluetui

## What bluetui replaces, and who it is for

On Linux, Bluetooth is managed by BlueZ, and the usual interactive interface to it is bluetoothctl. bluetui puts a ratatui interface on top of the same daemon. The README describes it plainly as a "TUI for managing bluetooth on Linux", and the prerequisites section names bluez as the only hard requirement. That framing tells you who the project is aimed at: someone already on a Linux desktop or laptop who is comfortable in a terminal and does not want to open a settings panel to turn an adapter on, run a scan, or unpair a headset.

The scope is deliberately narrow. bluetui manages adapters and devices. It does not configure audio profiles, it does not replace PipeWire or PulseAudio, and it does not ship a daemon of its own. If your problem is "my Bluetooth mouse will not reconnect", bluetui gives you the same primitives bluetoothctl does, arranged in panes you can move through with the keyboard. That is the whole value proposition, and it is a reasonable one for people who live in a terminal.

## How bluetui talks to BlueZ

The Cargo.toml is the clearest description of the architecture. The dependencies include bluer with the bluetoothd feature enabled, libdbus-sys with vendored D-Bus bindings, tokio for an async runtime, and ratatui with crossterm for rendering. So the data flow is: bluetui opens a D-Bus session, subscribes to BlueZ objects and properties through bluer, renders state into ratatui widgets, and translates key presses back into D-Bus calls. There is no intermediate service, no socket of its own, and no state file that outlives the process.

That design has consequences worth stating. Because the app is a client of the running daemon rather than a manager of it, bluetui cannot start bluetoothd for you, and it will not help if the daemon is masked or absent. It also means concurrent use is fine in principle: bluetoothctl and bluetui can both be attached to the same daemon, though they will not necessarily agree on what is on screen at any given moment. The README's usage section lists the actions that map onto that model: powering an adapter on or off, enabling or disabling discovery, pairing, connecting, trusting, favouriting, renaming and unpairing. Each of those is a BlueZ operation, not a bluetui invention.

## Installing bluetui and pairing a first device

The README lists several install routes: pre-built binaries from the release page, `cargo install bluetui` from crates.io, the Arch extra repository, Gentoo's net-wireless/bluetui, and x-cmd. Building from source is also documented. The crates.io route is the shortest if you already have a Rust toolchain:

```bash
cargo install bluetui
```

That places the binary in your Cargo bin directory, which is normally already on $PATH. On Arch, the packaged route is a single command:

```bash
pacman -S bluetui
```

After installing, run the binary with no arguments. The README notes that you might need Nerd Fonts installed for the icons to render correctly, so if you see placeholder glyphs rather than icons, that is the cause rather than a bug in the app.

Once the interface is up, the README documents `s` to start or stop scanning, `Tab` or `l` to move down between sections, `shift+Tab` or `h` to move up, and `j`/`k` or the arrow keys to scroll. In the new devices list, `Space` or `Enter` pairs the highlighted device. In the paired devices list, the same keys connect or disconnect, `u` unpairs, `t` toggles trust, `f` toggles favourite, and `e` renames. On the adapter pane, `p` toggles pairing mode, `o` toggles adapter power, and `d` toggles discovery. Quitting is `ctrl+c` or `q`, and the README notes that `Esc` also quits when `esc_quit = true` is set in the config.

Keybindings live in `$HOME/.config/bluetui/config.toml`, or at a custom path passed with `-c`. The README gives this example:

```toml
layout = "SpaceAround"
width = "auto"
toggle_scanning = "s"
esc_quit = false

[adapter]
toggle_pairing = "p"
toggle_power = "o"
toggle_discovery = "d"

[paired_device]
unpair = "u"
toggle_trust = "t"
toggle_favorite = "f"
rename = "e"
```

The `layout` key accepts "Legacy", "Start", "End", "Center", "SpaceAround" or "SpaceBetween", and `width` accepts `"auto"` or a positive integer. Those are the only config keys the README documents.

## Where bluetui is the wrong tool

The narrow scope cuts both ways. bluetui has no concept of audio routing, codecs or profile switching, so a user whose actual complaint is that a headset connects in the wrong mode will not find an answer here. It also has no tray icon and no desktop notifications; it is a full-screen terminal application you open, use and quit.

The prerequisite is the sharper limitation. bluetui requires BlueZ to be installed and running, and the README does not describe any fallback when it is not. If you are debugging a machine where bluetoothd will not start, or where the adapter is not detected at the kernel level, a BlueZ client cannot help you, because the thing it talks to is exactly what is broken. In that situation the useful tools are dmesg, rfkill and the systemd journal, not a TUI.

There is also the icon dependency. The README's note about Nerd Fonts is a soft requirement, and a terminal without a compatible font will show the interface with missing glyphs. That is cosmetic, but it is the kind of thing that makes a first run look broken when it is not.

## bluetui compared with bluetuith

The most direct comparison is bluetuith, which appears often enough in search traffic around this project that it is worth addressing. Both are terminal interfaces to BlueZ, and both are written in Go or Rust respectively, but the practical difference is in how much they try to do. bluetui stays close to adapter and device management: power, discovery, pairing, trust, favourite, rename, unpair. bluetuith is generally described as covering a wider set of Bluetooth tasks, including audio-oriented features, which is a different bet about what a terminal Bluetooth tool should be.

For someone choosing between them, the question is whether you want a small program that does the BlueZ primitives well or a larger one that attempts more of the stack. bluetui's dependency list is short and its README is explicit about the boundary. That is a trade-off in both directions: fewer moving parts, but you will still reach for another tool when the task is audio rather than pairing.

The same maintainer's impala project, referenced at the end of the README, applies the same approach to WiFi, which suggests the narrow-scope choice is deliberate rather than an early-stage gap.

## Maintenance, licence and the cost of upgrading

The repository is not archived. The last push was on 2026-08-28, which is recent, and the most recent release listed is v0.8.1 from 2026-01-17, following v0.8.0 and v0.7.2 in late 2025. That pattern suggests a project that releases when there is something to release rather than on a schedule, so an upgrade is not something you plan around; you take it when it appears.

Upgrade cost is low by design. The config file is small and the documented keys are a flat list plus two tables, so a version bump is unlikely to require rewriting a large configuration. The main risk in upgrading is behavioural rather than structural: a release that adds or changes a default keybinding will not break your config file, but it may change what an unbound key does. Since the README documents `-c` for pointing at a custom config path, keeping your own config out of the default location is a reasonable way to make upgrades predictable.

The licence is GPL-3.0, stated in both the README and the Cargo.toml package metadata. For a desktop utility that you run yourself, that is unremarkable. If you were considering bundling bluetui into a product, the copyleft terms would matter, and that is a question for a lawyer rather than for this article.

## Conclusion

Adopt bluetui if you run Linux with BlueZ, want adapter power, discovery and pairing handled from a terminal, and are willing to install a Nerd Font for the icons. Skip it if you need a graphical applet, a cross-platform client, or a tool that manages the Bluetooth daemon itself. Verify first that bluez is present and that bluetoothd is reachable over D-Bus on your machine, and check the config.toml keys against your own terminal's key handling before rebinding anything.

## FAQ

### How do I install bluetui?

The README lists several routes: pre-built binaries from the release page, `cargo install bluetui` from crates.io, the Arch extra repository via pacman, Gentoo's net-wireless/bluetui, and x-cmd. Building from source with `cargo build --release` is also documented and produces the binary at target/release/bluetui.

### Does bluetui work on Ubuntu or Debian?

The README does not list Ubuntu or Debian packages. The documented routes are the release binaries, crates.io, Arch, Gentoo and x-cmd, plus building from source. The only stated prerequisite is a Linux system with bluez installed.

### How do I change the keybindings in bluetui?

Edit $HOME/.config/bluetui/config.toml, or pass a custom path with -c. The README documents keys for scanning, quitting, layout and width, plus [adapter] and [paired_device] tables for the per-pane actions.

### Why are the icons in bluetui missing or blank?

The README notes that you might need Nerd Fonts installed for the icons to be displayed correctly. The app still runs without them; the glyphs are what fail to render.

### How do I pair a device in bluetui?

Press s to start scanning, move through the new devices list, and press Space or Enter on the highlighted device to pair it. The README also documents p on the adapter pane to enable or disable pairing mode.

## Sources

- [Issues](https://github.com/pythops/bluetui/issues)
- [License: GPL-3.0](https://github.com/pythops/bluetui/blob/master/LICENSE)
- [pythops/bluetui on GitHub](https://github.com/pythops/bluetui)
- [README](https://github.com/pythops/bluetui/blob/master/README.md)
- [Releases](https://github.com/pythops/bluetui/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pythops-bluetui